Create an Origin on Builder

An origin is a place on Chef Habitat Builder where you can store, share, and build packages. It is a unique namespace within Chef Habitat Builder, and while you can delete or transfer an origin, you can’t rename an origin after it is created. One example of an origin is the “core” origin, which is the set of foundational packages managed and versioned by the core Chef Habitat maintainers.

You can join existing origins by invitation and you can create your own origins. For more on invitations, see origin membership and RBAC.

Create an Origin

To create an origin, select the Create origin button on the My Origins page which opens the Create New Origin form. (Chef Habitat Builder > My Origins )

First, enter a unique name that you want to associate with your packages. Chef Habitat will only let you create an origin with a unique name. Some examples that you’ll see in Chef Habitat Builder are team names, user names, and abstract concepts.

Next, choose a privacy setting to set as the default for new packages. You can override this setting when uploading individual packages from the CLI or by connecting a plan file that declares a package as private. The difference between public and private packages is:

• Anyone can find and use public packages
• Only users with origin membership can find and use private packages

When you select Save and Continue, Chef Habitat Builder:

1. Creates your origin
2. Creates an origin key pair
3. Redirects Chef Habitat Builder to the origin page

Create an Origin with the Chef Habitat CLI

Use the hab origin commands to manage your origins from the command line.

Create an origin from the command line with the hab origin create command

hab origin create <origin>

The results of this command differ slightly from creating an origin on the Chef Habitat Builder site. The CLI command:

1. Creates an origin on the Chef Habitat Builder site
2. Does not generate an origin key pair

For more information, see the hab origin create CLI documentation.

Origin Membership & RBAC

Prerequisites:

• Download the Chef Habitat CLI
• Create a Chef Habitat Builder account
• Generate a personal access token
• Create an origin or accept an invitation to an existing origin
• Get origin keys

Role-Based Access Control (RBAC) for Chef Habitat Builder (SaaS and on-prem)

New in: 1.6.140

RBAC provides your organization with better operational safety by letting you assign specific levels of access to each user that belongs to an origin. With RBAC in place, existing standard origin ‘members’ from earlier versions are assigned the ‘Maintainer’ role. This role has similar permissions of the previous generic ‘member’ role, and the areas of difference are detailed below. The origin owner role remains unchanged.

When you join or create an origin, Chef Habitat Builder identifies your personal access token and assigns it a membership role for that origin. Your membership role defines the level of access that you have to the resources in an origin. By default, you’re assigned the “read-only” role when you join an origin, and you’re assigned the ‘owner’ role when you create an origin.

RBAC Origin Member Roles:

• Read-Only: This user can read an origin’s packages, channels, origin membership, jobs, keys, integrations, invitations, roles, settings but cannot add to, change, or delete anything else in the origin, including uploading packages and inviting users to the origin. Read-Only is the default membership role for users joining the origin.
• Member: In addition to read-only access, an origin ‘Member’ can upload and build packages in the ‘unstable’ channel, but they cannot promote packages to other channels.
• Maintainer: Existing origin ‘members’ are now ‘Maintainers’. This role has full read and write access to packages, channels, origin membership, jobs, integrations, invitations, settings. However, the ‘Maintainer’ role is more limited than the past role, in that ‘Maintainers’ only have read access to packages, channels, origin membership, jobs, keys, integrations, and settings. Origin ‘Maintainers’ can read origin membership roles and see and send invitations, but they cannot otherwise change origin membership–their own or anybody else’s. Finally, ‘Maintainers’ can neither read nor write origin secrets.
• Administrator: In addition to ‘Maintainer’ access, the ‘Administrator’ role adds the missing privileges for writing origin keys and membership roles, as well as for reading and writing origin secrets. Administrators have full read and write access to packages, channels, origin membership, jobs, keys, integrations, invitations, roles, secrets, settings.
• Owner: As in the past, the origin ‘Owner’ has full read and write access to the origin. Only Owners can delete the origin or transfer ownership to another member.

Comparison of RBAC Member Roles and Actions

Manage Origin Membership

In tandem with the changes to the Builder membership roles, we’ve also updated the hab CLI to support RBAC. We’re working on adding role management to the Chef Habitat Builder site, but in the meantime, you’ll need to use the CLI for now.

Manage origin membership with hab origin invitations

Manage Chef Habitat Builder origin membership with the Chef Habitat CLI, using the hab origin invitations command.

All Chef Habitat Builder users can accept, ignore, and see invitations for their accounts.

View origin invitations:

hab origin invitations list

Accept origin invitations:

hab origin invitations accept <ORIGIN> <INVITATION_ID>

Ignore origin invitations:

hab origin invitations ignore <ORIGIN> <INVITATION_ID>

Send origin membership invitations:

hab origin invitations send <ORIGIN> <INVITEE_ACCOUNT>

Origin administrators and owners can see all pending origin membership invitations:

hab origin invitations pending <ORIGIN>

Origin administrators and owners can rescind an origin membership invitation:

hab origin invitations rescind <ORIGIN> <INVITATION_ID>

Origin owners can transfer origin ownership to another member:

hab origin transfer [OPTIONS] <ORIGIN> <NEW_OWNER_ACCOUNT>

Manage membership roles with hab rbac

You can use role based access control (RBAC) from the command line. An origin MEMBER_ACCOUNT is the name used to sign in to Chef Habitat builder. You can find the list of user names on an origin’s Members Tab. (Builder > Origin > Members)

The RBAC command syntax is:

hab origin rbac <SUBCOMMAND>

The syntax for the show subcommand is:

hab origin rbac show <MEMBER_ACCOUNT> --origin <ORIGIN>

See an origin member’s RBAC role:

hab origin rbac show bluewhale --origin two-tier-app

The syntax for the set subcommand is:

hab origin rbac set [FLAGS] [OPTIONS] <MEMBER_ACCOUNT> <ROLE> --origin <ORIGIN>

Set an origin membership RBAC role with:

hab origin rbac set bluewhale admin --origin two-tier-app

Origin Keys

Prerequisites:

• Download the Chef Habitat CLI
• Create a Chef Habitat Builder account
• Generate a personal access token
• Create an origin with hab origin create or join an origin by invitation

When you create an origin, Chef Habitat Builder automatically generates origin keys. Origin key cryptography is asymmetric: it has a public origin key that you can distribute freely, and a private origin key that you should distribute only to users belonging to the origin. All Chef Habitat Builder users with access to the origin can view the origin public key revisions in the origin key tab (Builder > Origin > Keys) and download the origin public key, but only users with the origin ‘administrator’ or ‘owner’ roles can view or download the origin private key, or change the origin key pair.

Chef Habitat uses origin keys:

• When you build an artifact in your local environment, Chef Habitat signs the artifact with a public key
• When you upload an artifact to Chef Habitat Builder or Builder on-prem, Chef Habitat verifies that the artifact was signed with its public key
• When you install an artifact on a Chef Habitat Supervisor, Chef Habitat uses the public origin key to authorize the artifact’s installation; Chef Habitat only installs artifacts for which it has the public origin key
• When you download an artifact to your local environment, Chef Habitat uses the public origin key to verify the artifact’s integrity before it starts the installation

Chef Habitat Builder origin key names follow the format:

<origin>-<datetime>.pub (public key)
<origin>-<datetime>.sig.key (private key, also called a "signing key")

For example, in:

testorigin-20190416223046.pub
testorigin-20190416223046.sig.key

• “testorigin” is the origin’s name
• “20190416223046” is the date and time of the key’s creation, which was 2019-04-16 22:30:46.
• .pub is the file extension for the public key
• .sig.key is the file extension for the private key, which is also called a “signing key”

The Keys Tab

When you create an origin, Chef Habitat Builder automatically generates an origin key pair and saves both keys. To view your origin keys on Chef Habitat Builder, navigate to your origin and select the Keys tab. (Builder > Origins > Keys) You will always be able to view and download origin public keys, but you will only see the private keys for origins in which you are an “administrator” or “owner”.

Download Origin Keys

Download your private or public origin key by selecting the download icon from the right end of the key details, under the Actions heading.

Upload Origin Keys

You can upload origin keys that you generate on the command line to Chef Habitat Builder by selecting either the Upload a private key or Upload a public key icon, and copy your key into the form that appears.

Managing Origin Keys with the CLI

Run Chef Habitat CLI commands from your local environment or from within the Chef Habitat Studio.

See the CLI documentation for more information on the hab origin key commands.

Find Your Local Origin Keys

Chef Habitat stores your public and private origin keys at ~/.hab/cache/keys on Linux systems, C:\hab\cache\keys on Windows, and at /hab/cache/keys inside of the Chef Habitat Studio environment.

To find your origin keys in your local environment:

On Windows:

Get-ChildItem C:\hab\cache\keys

On Linux or macOS:

ls -la ~/.hab/cache/keys

To find your existing origin keys from inside of the Chef Habitat Studio:

On Windows:

Get-ChildItem C:\hab\cache\keys

On Linux or macOS:

ls -la /hab/cache/keys

Generate Origin Keys with the CLI

When you create an origin through the site, Chef Habitat Builder automatically generates an origin key pair.

The Chef Habitat CLI creates origin key pairs through two different commands, for two different uses:

• Use hab setup to generate your first origin key pair as part of setting up the hab CLI
• Use the hab origin key generate <ORIGIN> command to create an key pair for an origin created with the hab origin create command

Create origin keys with the hab command:

hab origin key generate <ORIGIN>

Download Origin Keys with the CLI

To get your public origin key using the command line, use:

hab origin key download <ORIGIN>

Upload Origin Keys with the CLI

Creating an origin with the hab origin create command registers the origin on Chef Habitat Builder without creating an origin key pair. The hab origin key generate command creates the key pair and saves them in your local environment, but it does not upload either origin key to Chef Habitat Builder.

• Only “administrators” and “owners” can upload new keys to an origin.
• Builder requires the public origin key to upload artifacts for that origin, so you’ll need to upload it.
• Builder requires the private origin key to enable new artifact builds from packages with plans linked to that origin.

Upload origin keys with the hab command:

hab origin key upload <ORIGIN>

Upload the origin private key:

hab origin key upload --secret <ORIGIN>

Upload both origin keys at the same time:

hab origin key upload  --secfile <PATH_TO_PRIVATE_KEY> --pubfile <PATH_TO_PUBLIC_KEY>

Import Origin Keys with the CLI

Use hab origin key import to read the key from a standard input stream into Chef Habitat Builder:

hab origin key import <enter or paste key>
hab origin key import <PATH_TO_KEY>
curl <URL_THAT_RETURNS_KEY> | hab origin key import

Troubleshoot Origin Key Import

On a macOS, you may encounter an upload failure. To remediate this failure:

• Check that your HAB_AUTH_TOKEN environment variable is properly set and initialized
• Add your SSL_CERT_FILE to the environment variables in your interactive shell configuration file, such as your .bashrc.

  export SSL_CERT_FILE=/usr/local/etc/openssl/cert.pem

Initialize the setting from the command line with:

 source ~/.bashrc

Origin Settings

The Origin Settings tab contains:

• Default Package Settings
• Origin Secrets

Everyone with origin membership can see the Settings tab, but only origin administrators and owners can add, update, or delete settings content.

Default Package Settings

The Default Package Settings define the visibility of build artifacts (.hart files). Everyone with origin membership can view the origin settings, but only origin administrators and owners can add, update, or delete settings.

• Public packages are visible in search results and can be used by every Chef Habitat Builder user
• Private artifacts do not appear in search results and are available only to users with origin membership

Change the default setting for the origin by switching from Public Packages to Private Packages. The default setting required for each origin and users with more than one origin can set some as public and others as private. Packages can have different default visibility settings than their origin’s. Change the default visibility setting in for individual packages in that package’s setting tab (Builder > Origin > Package > Settings).

Origin Secrets

Everyone with origin membership can view origin secrets, but only origin administrators and owners can add, update, or delete settings. Origin Secrets are located at the bottom of the Settings tab (Builder > Origin > Settings > Origin Secrets) and they let you encrypt and store secrets as environment variables. Origin secrets are useful for plans that require access to protected resources at build time, such as private source-code repositories and cloud storage providers.

Origin secrets are retained by the origin and are available for any of that origin’s packages. The origin secrets in your local environment are encrypted with an origin encryption key. Only Chef Habitat Builder can read encrypted origin secrets.

Manage Origin Secrets with the Chef Habitat CLI

You can view the list of origin secrets and delete them in Chef Habitat Builder. However, the primary way of interacting with origin secrets is with the Chef Habitat CLI.

List Secrets

To list all of the secrets in an origin, use:

hab origin secret list --origin <ORIGIN>

Set Origin Secrets as Environment Variables

Add your origin secrets as environment variables in your local environment:

export HAB_ORIGIN=<ORIGIN>
export HAB_AUTH_TOKEN=<TOKEN>
hab origin secret list

Save an Origin Secret

To save an origin secret give the secret a name and the key value:

hab origin secret upload AWS_ACCESS_KEY_ID <your-key-id>
hab origin secret upload AWS_SECRET_ACCESS_KEY <your-secret-access-key>

The output should similar to:

$ hab origin secret upload AWS_ACCESS_KEY_ID 1234567890EXAMPLE
↓ Downloading latest public encryption key
    79 B / 79 B | [========================================] 100.00 % 120.23 KB/s
☑ Cached habicat-20200123456789.pub
☛ Encrypting value for key AWS_ACCESS_KEY_ID.
✓ Encrypted AWS_ACCESS_KEY_ID=[REDACTED].
↑ Uploading secret for key AWS_ACCESS_KEY_ID.
✓ Uploaded secret for AWS_ACCESS_KEY_ID.

Delete an Origin Secret

To delete an origin secret from an origin with the CLI

hab origin secret delete AWS_ACCESS_KEY_ID
hab origin secret delete AWS_SECRET_ACCESS_KEY

See Using Origin Secrets in Plans for guidance on using origin secrets.

See the hab origin secret CLI documentation for more information on these commands.