diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/config.toml b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/config.toml index 0b4bca278e..9246494343 100644 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/config.toml +++ b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/config.toml @@ -1,79 +1,2 @@ [params.habitat] gh_path = "https://github.com/habitat-sh/habitat/tree/main/components/docs-chef-io/content/" - -#### -# Chef Habitat Menu -#### - -[[menu.habitat]] -title = "Chef Habitat" -identifier = "habitat" - - [[menu.habitat]] - title = "Install Habitat" - identifier = "habitat/install" - parent = "habitat" - weight = 15 - - [[menu.habitat]] - title = "Builder" - identifier = "habitat/builder" - parent = "habitat" - weight = 20 - - [[menu.habitat]] - title = "Origins" - identifier = "habitat/origins" - parent = "habitat" - weight = 30 - - [[menu.habitat]] - title = "Packages" - identifier = "habitat/packages" - parent = "habitat" - weight = 40 - - [[menu.habitat]] - title = "Plans" - identifier = "habitat/plans" - parent = "habitat" - weight = 50 - - [[menu.habitat]] - title = "Services" - identifier = "habitat/services" - parent = "habitat" - weight = 60 - - [[menu.habitat]] - title = "Supervisors" - identifier = "habitat/supervisors" - parent = "habitat" - weight = 70 - - [[menu.habitat]] - title = "Reference" - identifier = "habitat/reference" - parent = "habitat" - weight = 90 - - [[menu.habitat]] - title = "API" - identifier = "habitat/reference/api" - parent = "habitat/reference" - - [[menu.habitat]] - title = "Containers" - identifier = "habitat/containers" - parent = "habitat" - weight = 200 - - [[menu.habitat]] - title = "Diagrams" - identifier = "habitat/diagrams" - parent = "habitat" - weight = 500 - -#### -# End Chef Habitat Menu -#### diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_account.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_account.md index 91e1413568..61969576d5 100644 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_account.md +++ b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_account.md @@ -12,7 +12,7 @@ gh_repo = "habitat" +++ -Whether you are looking to leverage the SaaS or on-prem version of Chef Habitat Builder, you will need to create an account on the SaaS version of Chef Habitat Builder. After you have then downloaded the version, you will then sync the two accounts. +Whether you are looking to leverage the SaaS or on-prem version of Chef Habitat Builder, you'll need to create an account on the SaaS version of Chef Habitat Builder. After you have then downloaded the version, you'll then sync the two accounts. ## Prerequisites @@ -32,6 +32,6 @@ Head over to the Chef Habitat Builder sign-in page at [https://bldr.habitat.sh/# ![Chef Habitat sign in with Github](/images/habitat/builder_signin.png) -Signing in with your GitHub account and authorizing the Chef Habitat Builder application the first time you sign in grants you access to the Chef Habitat Builder platform. Once you've completed signing in and authorizing Chef Habitat Builder, you'll arrive at the 'My Origins' view. +Signing in with your GitHub account and authorizing the Chef Habitat Builder application the first time you sign in grants you access to the Chef Habitat Builder platform. Once you've completed signing in and authorizing Chef Habitat Builder, you'll arrive at the **My Origins** view. ![Authorize the Chef Habitat Application](/images/habitat/authorize.png) diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_origins.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_origins.md index a7011c0677..53dce2239a 100644 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_origins.md +++ b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_origins.md @@ -24,448 +24,5 @@ Progress Chef maintains the following origins: ## Where can I create an origin -You can create origins in an on-prem Habitat Builder deployment. -[Chef's public Habitat Builder](https://bldr.habitat.sh) doesn't support creating new origins. - -## Create an origin - -{{< readfile file="/habitat/reusable/md/create_origins_builder.md" >}} - -### Create an origin with the Chef Habitat CLI - -{{< readfile file="/habitat/reusable/md/create_origins_cli.md" >}} - -To create key pair for your origin, see the [origin keys](#origin-keys) documentation. - -## Origin membership and role-based access control - -Prerequisites: - -- [Download the Chef Habitat CLI]({{< relref "install_habitat" >}}) -- [Create a Chef Habitat Builder account]({{< relref "#builder-account" >}}) -- [Generate a personal access token]({{< relref "#builder-token" >}}) -- [Create an origin]({{< relref "#create-origin" >}}) or accept an invitation to an existing origin -- [Get origin keys]({{< relref "#origin-keys" >}}) - - -### Role-based access control (RBAC) for Chef Habitat Builder (SaaS and on-prem) - -New in: 1.6.140 - -Role-based access control (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. - -Chef Habitat Builder has the following 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 - -| Action | Read-Only | Member | Maintainer | Administrator | Owner | -|---------|-------|-------|-------|-------|-------| -| **Packages** | -| View packages | Y | Y | Y | Y | Y | -| Upload packages to `unstable` | N | Y | Y | Y | Y | -| Promote packages from `unstable` | N | N | Y | Y | Y | -| **Build Jobs** | -| View build jobs | Y | Y | Y | Y | Y | -| Trigger `unstable` build job | N | Y | Y | Y | Y | -| **Channels** | -| View channels | Y | Y | Y | Y | Y | -| Add/Update/Delete channels | N | N | Y | Y | Y | -| **Origin Keys** | -| View keys | Y | Y | Y | Y | Y | -| Add/Update/Delete keys | N | N | N | Y | Y | -| **Origin Membership** | -| View origin membership | Y | Y | Y | Y | Y | -| View invitations | Y | Y | Y | Y | Y | -| Send Invitations | N | N | Y | Y | Y | -| Revoke Invitations | N | N | Y | Y | Y | -| **Member Roles** | -| View member roles | Y | Y | Y | Y | Y | -| Update member roles | N | N | N | Y | Y | -| **Origin Settings** | -| View settings | Y | Y | Y | Y | Y | -| Add/Update/Delete settings | N | N | N | Y | Y | -| **Origin Secrets** | -| View secrets | N | N | N | Y | Y | -| Add/Update/Delete secrets | N | N | N | Y | Y | -| **Cloud Integrations** | -| View integrations | Y | Y | Y | Y | Y | -| Add/Update/Delete integrations | N | N | Y | Y | Y | -| **Ownership** | -| Transfer Origin | N | N | N | N | Y | -| Delete Origin | N | N | N | N | Y | - -### 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](/images/habitat/origin-members.png) - -#### Manage origin membership with `hab origin invitations` - -Manage Chef Habitat Builder origin membership with the Chef Habitat CLI, using the [hab origin invitations]({{< relref "habitat_cli/#hab-origin-invitations" >}}) command. - -All Chef Habitat Builder users can accept, ignore, and see invitations for their accounts. - -View origin invitations: - -```bash -hab origin invitations list -``` - -Accept origin invitations: - -```bash -hab origin invitations accept -``` - -Ignore origin invitations: - -```bash -hab origin invitations ignore -``` - -Send origin membership invitations: - -```bash -hab origin invitations send -``` - -Origin administrators and owners can see all pending origin membership invitations: - -```bash -hab origin invitations pending -``` - -Origin administrators and owners can rescind an origin membership invitation: - -```bash -hab origin invitations rescind -``` - -Origin owners can transfer origin ownership to another member: - -```bash -hab origin transfer [OPTIONS] -``` - -#### 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: - -```bash -hab origin rbac -``` - -The syntax for the `show` subcommand is: - -```bash -hab origin rbac show --origin -``` - -See an origin member's RBAC role: - -``` -hab origin rbac show bluewhale --origin two-tier-app -``` - -The syntax for the `set` subcommand is: - -```bash -hab origin rbac set [FLAGS] [OPTIONS] --origin -``` - -Set an origin membership RBAC role with: - -```bash -hab origin rbac set bluewhale admin --origin two-tier-app -``` - -## Origin keys - -Prerequisites: - -- [Download the Chef Habitat CLI]({{< relref "install_habitat" >}}) -- [Create a Chef Habitat Builder account]({{< relref "#builder-account" >}}) -- [Generate a personal access token]({{< relref "#builder-token" >}}) -- [Create an origin with `hab origin create` or join an origin by invitation]({{< relref "#create-origin" >}}) - -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. - -| Keys Actions | Read-Only | Member | Maintainer | Administrator | Owner | -|---------|-------|-------|-------|-------|-------| -| View keys | Y | Y | Y | Y | Y | -| Add/Update/Delete keys | N | N | N | Y | Y | - -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: - -```hab --.pub (public key) --.sig.key (private key, also called a "signing key") -``` - -For example, in: - -```hab -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" - -### 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". - -![Viewing your origin keys](/images/habitat/origin-keys.png) - -#### 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. - -![Detail of the download icon](/images/habitat/origin-key-download.png) - -#### 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. - -![Example form content for uploading an origin key in Builder](/images/habitat/builder-key-upload.png) - -### 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`]({{< relref "habitat_cli/#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. - -##### Find your origin keys in your local environment - -On Windows: - -```PowerShell -Get-ChildItem C:\hab\cache\keys -``` - -On Linux or macOS: - -```bash -ls -la ~/.hab/cache/keys -``` - -##### Find your existing origin keys from inside of the Chef Habitat Studio - -On Windows: - -```powershell -Get-ChildItem C:\hab\cache\keys -``` - -On Linux or macOS: - -```bash -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`]({{< relref "install_habitat" >}}) to generate your first origin key pair as part of setting up the `hab` CLI -- Use the `hab origin key generate ` command to create an key pair for an origin created with the `hab origin create` command - -Create origin keys with the `hab` command: - -```hab -hab origin key generate -``` - -#### Download origin keys with the CLI - -To get your public origin key using the command line, use: - -```hab -hab origin key download -``` - -#### 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 -hab origin key upload -``` - -Upload the origin private key: - -```hab -hab origin key upload --secret -``` - -Upload both origin keys at the same time: - -```hab -hab origin key upload --secfile --pubfile -``` - -#### 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 -hab origin key import -hab origin key import -curl | 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`. - - -```bash - export SSL_CERT_FILE=/usr/local/etc/openssl/cert.pem -``` - -Initialize the setting from the command line with: - -```bash - 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. - -| Settings Actions | Read-Only | Member | Maintainer | Administrator | Owner | -|---------|-------|-------|-------|-------|-------| -| View settings | Y | Y | Y | Y | Y | -| Add/Update/Delete settings | N | N | N | Y | Y | -| **Origin Secrets Actions** | -| View secrets | N | N | Y | Y | Y | -| Add/Update/Delete secrets | N | N | N | Y | Y | - -![The administrator or owner's view of the origin settings tab with a public default package setting and a saved origin secret](/images/habitat/origin-secrets.png) - -### 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 -hab origin secret list --origin -``` - -##### Set origin secrets as environment variables - -Add your origin secrets as environment variables in your local environment: - -```bash -export HAB_ORIGIN= -export HAB_AUTH_TOKEN= -hab origin secret list -``` - -##### Save an origin secret - -To save an origin secret give the secret a name and the key value: - -```hab -hab origin secret upload AWS_ACCESS_KEY_ID -hab origin secret upload AWS_SECRET_ACCESS_KEY -``` - -The output should similar to: - -```bash -$ 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 -hab origin secret delete AWS_ACCESS_KEY_ID -hab origin secret delete AWS_SECRET_ACCESS_KEY -``` - -See [Using Origin Secrets in Plans]({{< relref "plan_writing/#buildtime-workflow" >}}) for guidance on using origin secrets. - -See the [`hab origin secret`]({{< relref "habitat_cli/#hab-origin-secret" >}}) CLI documentation for more information on these commands. +You can create origins with [Habitat On-Prem Builder](/habitat/on_prem_builder/). +You can't create origins in [Chef's public Habitat Builder SaaS](https://bldr.habitat.sh). diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_overview.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_overview.md index 2f752bfeb3..be63533f56 100644 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_overview.md +++ b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_overview.md @@ -10,19 +10,21 @@ aliases = ["/habitat/using-builder/"] identifier = "habitat/builder/builder" parent = "habitat/builder" weight = 10 - +++ -Chef Habitat Builder acts as the core of Chef's Application Delivery Enterprise hub. Chef Habitat Builder was first launched as a cloud service and as the repository of all available plan templates built by Chef and the supporting community. Due to the fact that the application source code is stored alongside the build package, many users expressed a preference for storing packages and running Chef Habitat Builder on-prem. As a result, Chef Habitat Builder can be consumed either as a cloud based or on-premises solution. Plan files are stored in the Chef Habitat Builder SaaS, where they can be viewed and accessed by the Chef Habitat community and then shared with the on-premises version of the builder where they can then be copied and maintained locally. +Chef Habitat Builder is the core of Chef's Application Delivery Enterprise hub. +It was first launched as a cloud service and as the repository of all available plan templates built by Chef and the supporting community. +Since the application source code is stored alongside the build package, many users preferred storing packages and running [Chef Habitat On-prem Builder](/habitat/on_prem_builder/). +As a result, Chef Habitat Builder can be used as either a cloud-based or on-premises solution. +Plan files are stored in the Chef Habitat Builder SaaS, where they can be viewed and accessed by the Chef Habitat community and shared with Habitat On-prem Builder for local copying and maintenance. -## Chef Habitat Builder Enterprise Components Include: +## Chef Habitat Builder components -* **Application Manifest** - The Application Manifest provides a single application directory, which includes---at a minimum---the compiled app artifact, dynamic links to all direct and transitive runtime dependencies ,and instructions to install and run the app. -* **Deployment Channel Management** - Pre-canned deployment channels that can be used as-is or a user can custom design their own channels. Apps that are deployed through Chef Habitat can subscribe to a channel and be auto-upgraded whenever the app is promoted. -* **Origin Management** - Save your application delivery content in uniquely named spaces that you can control. -* **Content Library** - Hundreds of pre-built [application delivery packages](https://bldr.habitat.sh/#/pkgs/core) and core dependencies, which makes it easy to get started with Chef Habitat. -* **Custom Data and Reporting APIs** - Rich APIs enable the capability to export to CSV or JSON. -* **DevOps Integration APIs** - Provides an API so that clients can find and download the necessary packages to run their applications. Additional APIs also enable easy integration with other popular DevOps tools, including Jenkins, Terraform, Artifactory, Hashi Vault, and many others. -* **Role Based User Access** - Improves your organizations operational safety by letting you assign specific levels of access to each origin member. +- **Application Manifest**: The application manifest provides a single application directory, which includes, at a minimum, the compiled app artifact, dynamic links to all direct and transitive runtime dependencies, and instructions to install and run the app. +- **Deployment Channel Management**: Pre-canned deployment channels that you can use as-is or customize. Apps deployed through Chef Habitat can subscribe to a channel and be auto-upgraded whenever the app is promoted. +- **Content Library**: Hundreds of pre-built [application delivery packages](https://bldr.habitat.sh/#/pkgs/core) and core dependencies make it easy to get started with Chef Habitat. +- **Custom Data and Reporting APIs**: Rich APIs enable exporting data to CSV or JSON. +- **DevOps Integration APIs**: APIs allow clients to find and download the necessary packages to run their applications. Additional APIs enable integration with popular DevOps tools, including Jenkins, Terraform, Artifactory, Hashi Vault, and others. +- **Role-Based User Access**: Improves your organization's operational safety by letting you assign specific levels of access to each origin member. -For more information on how the SaaS and On-Prem versions of Chef Habitat Builder work together, read the blog - [Chef Habitat Builder On-Prem Enhancements that Extend Support to Airgap Environments and Simplify Set-Up](https://www.chef.io/blog/chef-habitat-product-announcement-builder-on-prem-enhancements-that-extend-support-to-airgap-environments-and-simplify-set-up) +For more information about how the SaaS and on-premises versions of Chef Habitat Builder work together, read the blog: [Chef Habitat Builder On-Prem Enhancements that Extend Support to Airgap Environments and Simplify Set-Up](https://www.chef.io/blog/chef-habitat-product-announcement-builder-on-prem-enhancements-that-extend-support-to-airgap-environments-and-simplify-set-up). diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_profile.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_profile.md index fbe34833a6..1437404203 100644 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_profile.md +++ b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_profile.md @@ -13,109 +13,131 @@ gh_repo = "habitat" weight = 30 +++ -Whether you are looking to leverage the SaaS or on-prem version of Chef Habitat Builder, you will need to create an account on the SaaS version of Chef Habitat Builder. After you have then downloaded the version, you will then sync the two accounts. +To use the SaaS or on-premises version of Chef Habitat Builder, you need to create an account on the SaaS version. After downloading the version, sync the two accounts. -This documentation covers everything from creating an account to setting up automated builds and exporting packages to a variety of container registries. - -## Get an Account +## Get an account ### Prerequisites -You need to set a few things up before you can get started with Chef Habitat Builder: +Set up the following before getting started with Chef Habitat Builder: -* Download and install the [Chef Habitat CLI]({{< relref "install_habitat" >}}) -* A [GitHub account](https://github.com/join) +- Download and install the [Chef Habitat CLI]({{< relref "install_habitat" >}}) +- A [GitHub account](https://github.com/join) -### Sign-in and Authorize Chef Habitat Builder +### Sign in and authorize Chef Habitat Builder -Chef Habitat Builder automatically creates your account the first time you sign in using the GitHub authentication process. You'll also need to authorize the Chef Habitat Builder application in Github. +Chef Habitat Builder automatically creates your account the first time you sign in using GitHub authentication. You'll also need to authorize the Chef Habitat Builder application in GitHub. -Head over to the Chef Habitat Builder sign-in page at [https://bldr.habitat.sh/#/sign-in](https://bldr.habitat.sh/#/sign-in) to get started. +Go to the [Chef Habitat Builder sign-in page](https://bldr.habitat.sh/#/sign-in) to get started. -1. To sign in with an existing GitHub account, select **Sign in with GitHub** -1. If you need to set up a GitHub account, select the **Sign up here** link +1. To sign in with an existing GitHub account, select **Sign in with GitHub**. +1. To set up a GitHub account, select the **Sign up here** link. -![Chef Habitat sign in with Github](/images/habitat/builder_signin.png) +Signing in with your GitHub account and authorizing the Chef Habitat Builder application grants you access to the platform. After signing in and authorizing, you'll arrive at the **My Origins** page. -Signing in with your GitHub account and authorizing the Chef Habitat Builder application the first time you sign in grants you access to the Chef Habitat Builder platform. Once you've completed signing in and authorizing Chef Habitat Builder, you'll arrive at the 'My Origins' view. +## Set up your Habitat Builder profile -![Authorize the Chef Habitat Application](/images/habitat/authorize.png) +Use the **Profile** page to: -## Set up your Profile +- View the GitHub account used to sign in. +- Add an email to your profile. +- Create your personal access token. +- Add a Progress Chef license key. -Use the _Profile_ tab to: +Access your profile by selecting the **round icon at the top right corner** of any page, then select **Profile** from the menu. -* See the GitHub account used to sign in -* Add an email to your profile -* Create your personal access token +{{< note >}} -Access your profile by selecting the **round icon at the top right corner** of any page. Select the **profiles** option from the drop-down menu to customize your profile and create your personal access token. +A Progress Chef license key is required to access [Chef Habitat SaaS Builder](https://bldr.habitat.sh) and a personal access token is required to download or build packages from [Chef Habitat SaaS Builder](https://bldr.habitat.sh). -![Access your Chef Habitat Builder profile](/images/habitat/builder_profile.png) +This requirement applies to all new Chef product releases, such as Infra 19, Habitat 2.0, and InSpec 7, and their dependencies from Chef Habitat SaaS Builder. -### Register an Email Address +It doesn't apply to existing Chef product releases, such as Chef Infra Client 18.x and Habitat 1.x, or related packages in the stable channel. -Adding an email address to your profile gives the Chef Habitat team permission to contact you directly about important information. If you use an email address associated with a GitHub account, it will also use your GitHub avatar. Save your changes by selecting **save**. +This requirement applies to the following `hab` CLI commands: -![Register your email address](/images/habitat/builder_profile_user.png) +- `hab pkg download` +- `hab pkg build` +- `hab pkg install` +- `hab studio enter` +- `hab studio build` +- `hab studio new` +- `hab studio run` -### Create a Personal Access Token +{{< /note >}} -Chef Habitat Builder uses an access token, called a _personal access token_ or a _Habitat authentication token_ (HAB_AUTH_TOKEN), to give you access to actions that you would like to take on Chef Habitat Builder. The _personal access token_ is the first level of permissions that you need to for any interactions with Chef Habitat Builder, such as uploading packages or checking the status of build jobs. +### Add a Progress Chef license key -Create your personal access token at the bottom of the profile page (below the save button), by selecting **Generate Token**. +To download and sync official Chef-maintained packages from Chef Habitat SaaS Builder to an on-premises Builder instance, you need a valid license key. -![Create your personal access token](/images/habitat/generate-token.png) +To add your license key, follow these steps: -Your generated access token will appear in the field. The access token is visible in the tab once, and navigating away from or reloading the page will cause it to vanish from the display. Copy your access token by selecting the icon on the right side of the field and set it as an environment variable before continuing. +1. If you're an enterprise user, log into your customer portal and copy the license key linked to your asset. -![Copy your personal access token](/images/habitat/copy-token.png) + Free or trial users can get a [free or trial license key](https://www.chef.io/license-generation-free-trial). -#### Set the personal access token as a Windows Environment Variable +1. Log into [Chef Habitat SaaS Builder](https://bldr.habitat.sh). If you haven't entered your license key, a pop-up will prompt you to do so. -You can use your personal access token as a [Windows environment variable](https://docs.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_environment_variables?view=powershell-7) for a single session by passing it in the command line or save it in your user settings for use across sessions. + Enter your license key in the field provided and select **Proceed**. Once entered, your account will be authorized to view and download official Chef-maintained packages. -Save your personal authorization token as a permanent environment variable in Windows using: +### Register an email address -```PS -SETX HAB_AUTH_TOKEN /m -``` +Adding an email address to your profile allows the Chef Habitat team to contact you about important information. If you use an email address associated with a GitHub account, it will also use your GitHub avatar. Save your changes by selecting **Save**. + +### Create a personal access token + +Chef Habitat Builder uses a personal access token (`HAB_AUTH_TOKEN`) to authorize actions from the `hab` CLI, such as uploading packages or checking build job statuses. + +To create your personal access token: -Replacing with the contents of your generated personal access token. +1. Go to the bottom of the profile page and select **Generate Token**. -You can also save your personal access token as a permanent environment variable using the Windows user interface. In your Windows help bar, enter `environment` and select **Edit the system environment variables** from the list of suggestions. +1. Copy the generated token by selecting the icon on the right side of the field. The token is visible only once. If you navigate away or reload the page, it will disappear. Save it as an environment variable before continuing. -This opens the `System Properties` window on the `Advanced` tab. Select the `Environment Variables` button. +#### Set the personal access token as a Windows environment variable -![Navigate to Windows Environment Variables](/images/habitat/environment_variable.png) +To use your token in a single session, pass it in the command line. To use it across sessions, save it as a permanent environment variable. -In the next window, select the `New` button in the top part. This opens a dialog box that lets you set individual user variables. +To save it permanently, use: -![Make new user variable](/images/habitat/environment_variable_new.png) +```PS1 +SETX HAB_AUTH_TOKEN /m +``` + +Replace `` with your generated token. + +You can also save it through the Windows user interface: -Create a permanent environment variable by entering `HAB_AUTH_TOKEN` as the variable name. Next, paste the authorization token that you copied after you generated a new token on your profile page as the variable value. After you select the `OK`, you will see the new token in the user variables field. +1. Search for "environment" in the Windows help bar and select **Edit the system environment variables**. +1. In the **System Properties** window, select **Environment Variables**. +1. In the next window, select **New** under user variables. +1. Enter `HAB_AUTH_TOKEN` as the variable name and paste your token as the value. Select **OK** to save. -![Save your HAB_AUTH_TOKEN](/images/habitat/environment_variable_new_var.png) +To test, open Command Prompt and enter: + +```cmd +echo %HAB_AUTH_TOKEN% +``` -To test that your new token works correctly, open the Command Prompt---which you can find by entering command in the Windows search box---and entering `echo %HAB_AUTH_TOKEN%`. You should see the value that you pasted into the environment variable. +You should see your token value. -#### Set the personal access token as a macOS Environment Variable +#### Set the personal access token as a macOS environment variable -Set the `HAB_AUTH_TOKEN` in the CLI with: +To set the token for the current session, use: ```bash -export HAB_AUTH_TOKEN= +export HAB_AUTH_TOKEN= ``` -Replacing `` with the contents of your generated personal access token. +Replace `` with your generated token. -To use your personal access token across sessions, set it as an environment variable in your interactive shell configuration file, such as your `.bashrc`. +To use it across sessions, add it to your shell configuration file (for example, `.bashrc`): ```bash -export HAB_AUTH_TOKEN= +export HAB_AUTH_TOKEN= ``` -Then initialize the path from the command line, by running: +Then initialize the path with: ```bash source ~/.bashrc diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/copy-token.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/copy-token.png deleted file mode 100644 index 2e71f2f584..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/copy-token.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/generate-token.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/generate-token.png deleted file mode 100644 index 963e091e78..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/generate-token.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/config.toml b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/config.toml new file mode 100644 index 0000000000..4a689b4204 --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/config.toml @@ -0,0 +1,2 @@ +[params.on-prem-builder] +gh_path = "https://github.com/habitat-sh/on-prem-builder/tree/main/docs-chef-io/content/" diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/_index.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/_index.md new file mode 100644 index 0000000000..ef4a2eb077 --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/_index.md @@ -0,0 +1,56 @@ ++++ +title = "About Chef Habitat On-Prem Builder" + +[cascade] + [cascade.params] + gh_repo = "on-prem-builder" + product = ["habitat"] + +[menu] + [menu.habitat] + title = "About On-Prem Builder" + identifier = "habitat/on-prem-builder/overview" + parent = "habitat/on-prem-builder" + weight = 10 ++++ + +Chef Habitat On-Prem Builder is the preferred and fully supported method for hosting and managing Habitat packages within your organization's infrastructure. +It provides a secure, private, and compliant environment for managing your software artifacts and is ideal for both connected and air-gapped environments. + +You can deploy Chef Habitat On-Prem Builder and privately host Chef Habitat packages and associated artifacts such as keys. +You can direct Chef Habitat clients (such as the `hab` cli, Supervisors, and Studios) to your On-Prem Builder deployment, which allows you to develop, execute, and manage packages without depending on the public Chef Habitat services. + +## Audience + +This documentation is for anyone who wishes to host Chef Habitat packages in their own infrastructure. + +## Features + +Once installed, you'll be able to do the following: + +- Log into Chef Habitat On-Prem Builder. +- Create origins, keys, and access tokens. +- Invite users to origins. +- Upload and download Chef Habitat packages. +- Promote and demote Chef Habitat packages to channels. +- Normal interactions using the `hab` client with the Chef Habitat Builder API. +- Package builds using the `hab` client and Chef Habitat Studio. +- Import core packages from the upstream Chef Habitat SaaS Builder. + +The following Chef Habitat SaaS Builder features aren't available with On-Prem Builder: + +- automated package builds +- automated package exports + +## Resources + +- [on-prem-builder GitHub repository](https://github.com/habitat-sh/on-prem-builder) +- [habitat GitHub repository](https://github.com/habitat-sh/habitat) +- [Progress Chef Community](https://community.progress.com/s/products/chef) +- [Chef Community Slack](https://community.chef.io/slack) +- [Chef Discourse](https://discourse.chef.io/) + +## More information + +- [Chef Habitat CLI](/habitat/habitat_cli/) +- [Chef Automate and Chef Habitat Builder](/automate/on_prem_builder/) diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/_index.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/_index.md new file mode 100644 index 0000000000..a57ccfe0e2 --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/_index.md @@ -0,0 +1,22 @@ ++++ +title = "Chef Habitat On-Prem Builder" + +[menu] + [menu.habitat] + title = "Overview" + identifier = "habitat/on-prem-builder/configure/overview" + parent = "habitat/on-prem-builder/configure" + weight = 10 ++++ + +See the following guides to configure Chef Habitat On-Prem Builder: + +- [Configure Artifactory as an object store](artifactory). +- [Configure disaster recovery or warm spare deployment](disaster_recovery_warm_spare). +- [Configure Habitat Builder logs](logs). +- [Scale frontend Habitat Builder nodes](scale_frontend_nodes). +- [Separate backend services onto separate nodes](separate_backend_services). + +See the following Chef Habitat On-Prem Builder example config file: + +- [example Habitat Builder config file](builder_config_example) diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/artifactory.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/artifactory.md new file mode 100644 index 0000000000..ae386fb6de --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/artifactory.md @@ -0,0 +1,45 @@ ++++ +title = "Use Artifactory as a Habitat package artifact store" + +[menu] + [menu.habitat] + title = "Use Artifactory as a package artifact store" + identifier = "habitat/on-prem-builder/configure/artifactory" + parent = "habitat/on-prem-builder/configure" + weight = 30 ++++ + +You can use an existing Artifactory instance as your object store instead of MinIO. +This feature is available as an early preview for testing. + +## Configure Habitat Builder to use Artifactory as an object store + +Before you start, make sure you have: + +- The URL of your Artifactory instance. +- An API key to authenticate with Artifactory. +- An Artifactory repository for storing Habitat artifacts. + +To use an Artifactory instance as your object store, follow these steps: + +1. If you don't have it already on your system, clone the [habitat-sh/on-prem-builder repository](https://github.com/habitat-sh/on-prem-builder). +1. Update your `bldr.env` file using the Artifactory settings in [`bldr.env.sample`](https://github.com/habitat-sh/on-prem-builder/blob/main/bldr.env.sample). +1. Install Habitat On-Prem Builder as usual with the `install.sh` script. +1. Optional: Sign in to Habitat Builder, create an origin, upload some packages, and verify that the packages appear in your specified Artifactory repository. + +If you have issues, see the support section below. + +## Test a local Artifactory instance + +To quickly test with a local Artifactory instance, run: + +```bash +sudo hab svc load core/artifactory +``` + +This command starts a local Artifactory instance. +You can view it at: `http://localhost:8081/artifactory/webapp/#/home` + +## Manage Builder artifacts on Artifactory + +If you use Artifactory for your Habitat On-Prem Builder artifact store, read about [Artifactory's best practices for disaster recovery](https://jfrog.com/whitepaper/best-practices-for-artifactory-backups-and-disaster-recovery/). diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/builder_config_example.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/builder_config_example.md new file mode 100644 index 0000000000..5a1f1ba1da --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/builder_config_example.md @@ -0,0 +1,110 @@ ++++ +title = "Example builder.env configuration file" + +[menu] + [menu.habitat] + title = "Example builder.env config file" + identifier = "habitat/on-prem-builder/configure/builder.env" + parent = "habitat/on-prem-builder/configure" + weight = 20 ++++ + +This is an example of the Chef Habitat On-Prem Builder `builder.env` configuration file. +Also, see the [`builder.env.sample` file](https://github.com/habitat-sh/on-prem-builder/blob/main/bldr.env.sample) in the on-prem-builder repository. + +```shell +#!/bin/bash + +# The endpoint and port for your Postgresql instance +# Change only if needed +export POSTGRES_HOST=localhost +export POSTGRES_PORT=5432 + +# The endpoint, key and secret for your MinIO instance (see README) +# Change these before the first install if needed +export MINIO_ENDPOINT=http://localhost:9000 +export MINIO_BUCKET=habitat-builder-artifact-store.local +export MINIO_ACCESS_KEY=depot +export MINIO_SECRET_KEY=password + +# If you'd like to use Artifactory instead of MinIO, uncomment +# and set the following variables appropriately. +# IMPORTANT: See the README for more info +# export ARTIFACTORY_ENABLED=true +# export ARTIFACTORY_API_URL=http://localhost:8081 +# export ARTIFACTORY_API_KEY=foo +# export ARTIFACTORY_REPO=habitat-builder-artifact-store + +# Modify these as needed for the on-premise OAuth2 provider. +# The variables below are configured for GitHub by default, +# but appropriate values for Bitbucket, GitLab, Azure AD and Okta +# are also included as comments. + +# Whether SSL is enabled for the on-prem depot +export APP_SSL_ENABLED=false + +# The URL for this instance of the on-prem depot +# IMPORTANT: If SSL is enabled, APP_URL should start be https +export APP_URL=http://localhost + +# The OAUTH_PROVIDER value can be "github", "gitlab", "bitbucket", "azure-ad", +# "okta" or "chef-automate" +export OAUTH_PROVIDER=github +# export OAUTH_PROVIDER=bitbucket +# export OAUTH_PROVIDER=gitlab +# export OAUTH_PROVIDER=azure-ad +# export OAUTH_PROVIDER=okta +# export OAUTH_PROVIDER=chef-automate + +# The OAUTH_USERINFO_URL is the API endpoint that will be used for user info +export OAUTH_USERINFO_URL=https://api.github.com/user +# export OAUTH_USERINFO_URL=https://api.bitbucket.org/1.0/user +# export OAUTH_USERINFO_URL=https://gitlab.com/oauth/userinfo +# export OAUTH_USERINFO_URL=https://login.microsoftonline.com//openid/userinfo +# export OAUTH_USERINFO_URL=https://.com/oauth2/v1/userinfo +# export OAUTH_USERINFO_URL=https:///session/userinfo + +# The OAUTH_AUTHORIZE_URL is the *fully qualified* OAuth2 authorization endpoint +export OAUTH_AUTHORIZE_URL=https://github.com/login/oauth/authorize +# export OAUTH_AUTHORIZE_URL=https://bitbucket.org/site/oauth2/authorize +# export OAUTH_AUTHORIZE_URL=https://gitlab.com/oauth/authorize +# export OAUTH_AUTHORIZE_URL=https://login.microsoftonline.com//oauth2/authorize +# export OAUTH_AUTHORIZE_URL=https://.com/oauth2/v1/authorize +# export OAUTH_AUTHORIZE_URL=https:///session/new + +# The OAUTH_SIGNUP_URL is the link used to register users with the OAUTH provider +export OAUTH_SIGNUP_URL=https://github.com/join +# export OAUTH_SIGNUP_URL=https://bitbucket.org/account/signup/ +# export OAUTH_SIGNUP_URL=https://gitlab.com/users/sign_in#register-pane + +# The OAUTH_TOKEN_URL is the *fully qualified* OAuth2 token endpoint +export OAUTH_TOKEN_URL=https://github.com/login/oauth/access_token +# export OAUTH_TOKEN_URL=https://bitbucket.org/site/oauth2/access_token +# export OAUTH_TOKEN_URL=https://gitlab.com/oauth/token +# export OAUTH_TOKEN_URL=https://login.microsoftonline.com/tenant-id/oauth2/token +# export OAUTH_TOKEN_URL=https://your.okta.domain.com/oauth2/v1/token +# export OAUTH_TOKEN_URL=https:///session/token + +# The OAUTH_REDIRECT_URL is the registered OAuth2 redirect +# IMPORTANT: If SSL is enabled, the redirect URL should be https +export OAUTH_REDIRECT_URL=http://localhost/ + +# The OAUTH_CLIENT_ID is the registered OAuth2 client id +export OAUTH_CLIENT_ID=0123456789abcdef0123 + +# The OAUTH_CLIENT_SECRET is the registered OAuth2 client secret +export OAUTH_CLIENT_SECRET=0123456789abcdef0123456789abcdef01234567 + +# Modify these only if there is a specific need, otherwise leave as is +export BLDR_CHANNEL=on-prem-stable +export BLDR_ORIGIN=habitat +export HAB_BLDR_URL=https://MY_ON_PREM_URL/ +# From the Automate CLI use +# export HAB_BLDR_URL=https://MY_ON_PREM_URL/bldr/v1/ + +# Help us make Habitat better! Opt into analytics by changing the ANALYTICS_ENABLED +# setting below to true, then optionally provide your company name. (Analytics is +# disabled by default. See our privacy policy at https://www.habitat.sh/legal/privacy-policy/.) +export ANALYTICS_ENABLED=false +export ANALYTICS_COMPANY_NAME="" +``` diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/disaster_recovery_warm_spare.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/disaster_recovery_warm_spare.md new file mode 100644 index 0000000000..51cf552ea6 --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/disaster_recovery_warm_spare.md @@ -0,0 +1,76 @@ ++++ +title = "Configure Chef Habitat On-Prem Builder for disaster recovery or a warm spare deployment" + +[menu] + [menu.habitat] + title = "Configure disaster recovery or warm spare" + identifier = "habitat/on-prem-builder/configure/disaster recovery" + parent = "habitat/on-prem-builder/configure" + weight = 30 ++++ + +To quickly recover from an outage or perform planned upgrades or maintenance, you can use a warm spare or disaster recovery installation. + +## High availability + +The only supported high availability solution is to use SaaS backend services, such as AWS RDS and AWS S3. +There is no fully on-premises solution for highly available Habitat Builder services. + +## Configure disaster recovery or warm spare + +The following architecture diagram shows how data synchronization increases the availability of the Builder API and backend for disaster recovery and warm spare scenarios. + +![Habitat On-Prem Builderises architecture](/images/habitat/on_prem_builder/builder_architecture.png) + +### Synchronize components + +To enable a disaster recovery or a warm spare deployment, provision the same number of frontend and backend systems as your primary location. +These systems serve as your disaster recovery or warm spare environment. +For disaster recovery, deploy them in a separate availability zone with separate storage. + +Builder stores lightweight data, so backup and disaster recovery or warm spare strategies are straightforward. +Habitat Builder has two types of data you should back up in case of a disaster or when transferring workloads to a warm spare: + +- PostgreSQL package and user metadata +- Habitat artifacts (`.hart` files) + +Back up or replicate all data using highly available storage systems as described in the following sections. + +Coordinate the entire On-Prem Builder cluster backups to happen together. +However, because Builder stores only metadata and artifacts, you have some flexibility in backup timing. +If a package's metadata is missing from PostgreSQL, you can repopulate it by re-uploading the package with the `--force` flag. +For example: + +```bash +hab pkg upload -u --force +``` + +### PostgreSQL + +If you use AWS RDS, take periodic snapshots of the RDS instance. +For disaster recovery, use a Multi-AZ RDS deployment. + +For non-RDS deployments, back up PostgreSQL data as described in the [Habitat Builder PostgreSQL documentation](../../manage/postgres). + +Periodically restore backups into the disaster recovery or warm spare environment using a scheduled automated process, such as a cron job. +You can run the restore remotely from the same host that created the backup. +The Builder database is typically small, usually only tens of megabytes. + +### Habitat artifacts + +Habitat artifacts are stored in one of two locations: + +- MinIO +- S3 bucket + +If your backend uses MinIO for artifact storage, make sure it is backed by highly available storage. +Back up MinIO data as described in the [Habitat Builder MinIO documentation](../../manage/minio). +If you use a warm spare in the same availability zone or data center and the filesystem is network-attached, you can attach it to the warm spare. +However, only one Builder cluster should accept live traffic when sharing the same filesystem. +For disaster recovery, replicate the filesystem to the alternate availability zone or data center. + +If artifacts are stored in an S3 bucket, you can use the same bucket for a warm spare in the same availability zone or data center. +For disaster recovery, replicate the S3 bucket to the alternate availability zone or data center. +AWS S3 provides built-in replication for this purpose. + +If you don't re-attach the MinIO filesystem to the warm spare, periodically restore backups into the disaster recovery or warm spare environment using a scheduled automated process, such as a cron job. diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/logs.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/logs.md new file mode 100644 index 0000000000..fb99d2da5b --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/logs.md @@ -0,0 +1,87 @@ ++++ +title = "Configure Habitat Builder logs" + +[menu] + [menu.habitat] + title = "Configure Builder logs" + identifier = "habitat/on-prem-builder/configure/logs" + parent = "habitat/on-prem-builder/configure" + weight = 40 ++++ + +This page explains how to configure Chef Habitat On-Prem Builder logs. + +## Supported log levels + +You can set the log level to `error`, `warn`, `info`, `debug`, or `trace`. +For more details about logging in Chef Habitat, see the [Supervisor log configuration reference](/habitat/sup_log_configuration/) and the [Supervisor log key documentation](/habitat/sup_log_keys/). + +## Configure the Habitat Builder log level + +To enable and review debug logging for services in your Habitat installation, follow these steps: + +1. Open the `/hab/user/builder-api/config/user.toml` file. +1. Set the value of `log_level` on the first line: + + ```toml + log_level=",tokio_core=error,tokio_reactor=error,zmq=error,hyper=error" + ``` + + Replace `` with the desired log level, such as `debug` or `error`. + +1. Save and close the file. +1. Restart Habitat: + + ```sh + sudo systemctl restart hab-sup + ``` + +1. To view the logs, run: + + ```sh + journalctl -fu hab-sup + ``` + +## Configure Rust logging + +You can use the `RUST_LOG` environment variable to enable detailed logging and backtraces in Habitat Builder. + +To see debug output and backtraces for a specific Habitat command, run: + +```bash +# Linux/macOS +env RUST_LOG=debug RUST_BACKTRACE=1 +``` + +Replace `` with a Habitat CLI command, such as `hab sup run`. + +To set Rust logging for Habitat Builder, follow these steps: + +1. Open the `/hab/svc/builder-api/user.toml` file. +1. Set the second line to: + + ```toml + RUST_LOG=debug RUST_BACKTRACE=1 + ``` + +### Log rotation + +The `builder-api-proxy` service logs all access and errors (through Nginx) to log files in your service directory. +Because these files can grow large, you may want to set up log rotation. +The following sample logrotate configuration shows how you can manage these log files: + +```bash +/hab/svc/builder-api-proxy/logs/host.access.log +/hab/svc/builder-api-proxy/logs/host.error.log +{ + rotate 7 + daily + missingok + notifempty + delaycompress + compress + postrotate + /bin/kill -USR1 `cat /hab/svc/builder-api-proxy/var/pid 2>/dev/null` 2>/dev/null || true + endscript +} +``` diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/scale_frontend_nodes.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/scale_frontend_nodes.md new file mode 100644 index 0000000000..52d5989afd --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/scale_frontend_nodes.md @@ -0,0 +1,91 @@ ++++ +title = "Scale frontend Habitat Builder nodes" + +[menu] + [menu.habitat] + title = "Scale Builder frontend" + identifier = "habitat/on-prem-builder/configure/frontend scaling" + parent = "habitat/on-prem-builder/configure" + weight = 50 ++++ + +With any tiered or high-availability deployment of Habitat Builder services, you'll likely want to scale your frontend nodes horizontally. +The most common deployment pattern for this use case is a pool of frontend nodes behind a load balancer. + +## System recommendations for multiple frontend nodes + +The hardware requirement for an API node is low. +However, your node count and usage statistics might change this recommendation. +For example, Chef's Habitat Builder SaaS uses compute-optimized machines with 36 vCPUs and 60 GB of RAM. +This setup supports a live SaaS service with thousands of supervisors checking in at any time. +Disk space doesn't matter on a new API node because the API shouldn't put disk resources into contention, except possibly for logging. + +These are only recommendations, and we can't guarantee performance at these scales. +You should run these nodes in a pool behind a load balancer. + +For a small deployment (tens of nodes): + +- CPU: 2 vCPUs +- RAM: 4 GB +- Disk: 20 GB + +For a mid-sized deployment (hundreds of nodes): + +- CPU: 8 vCPUs +- RAM: 16 GB +- Disk: 20 GB + +For a large deployment (thousands of nodes): + +- CPU: 16 or more vCPUs +- RAM: 32 GB or more +- Disk: 20 GB + +## Configure node ports + +The Habitat On-Prem Builder `install.sh` script supports scaling frontend nodes as a deployment pattern. +You must deploy new frontend nodes on separate compute resources from your initial on-prem deployment. +Because Habitat Builder services need to communicate across your network between the frontend and backend nodes, you need to open the following ports to these nodes to ensure your Habitat On-Prem Builder works correctly: + +- TCP 9638 - Habitat configuration gossip +- UDP 9638 - Habitat configuration gossip +- TCP 9636 - Builder API HTTP +- TCP 5432 - PostgreSQL +- TCP 9000 - MinIO +- TCP 11211 - Memcached + +## Create a Builder config file + +The `bldr.env` file for your single On-Prem Builder node contains most of the information you need to bootstrap a new frontend and is used to configure Builder durin installation. + +1. On each node that you plan run as a frontend node, clone the [habitat-sh/on-prem-builder repository](https://github.com/habitat-sh/) or download and extract an [on-prem-builder release](https://github.com/habitat-sh/on-prem-builder/releases). + +1. Create the `bldr.env` file by duplicating the sample file in the on-prem-builder repository: + + ```sh + cp bldr.env.sample bldr.env + ``` + +1. On the `bldr.env` file update the following settings: + + - Update the values of `OAUTH_REDIRECT_URL`, `OAUTH_CLIENT_ID`, and `OAUTH_CLIENT_SECRET` to match your on-premises OAuth2 provider. + + - If your Habitat On-Prem Builder cluster uses cloud services and you run multiple frontend instances, set `OAUTH_REDIRECT_URL` to your load balancer. + + - If you don't use cloud services, update the values of `POSTGRES_HOST` and `MINIO_ENDPOINT`. + + - Add all frontend and backend nodes hosting builder services to `HAB_BLDR_PEER_ARG` in the following format: + + ```shell + HAB_BLDR_PEER_ARG="--peer --peer --peer " + ``` + + Replace `` with a node IP address or hostname. + +### Install a frontend node + +Install the Habitat Builder frontend services, by running the frontend install script on each new node: + +```shell +./install.sh --install-frontend +``` diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/separate_backend_services.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/separate_backend_services.md new file mode 100644 index 0000000000..aeb71dbf16 --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/separate_backend_services.md @@ -0,0 +1,119 @@ ++++ +title = "Separate Habitat Builder's backend services onto separate nodes" + +[menu] + [menu.habitat] + title = "Separate backend services" + identifier = "habitat/on-prem-builder/configure/Separating backend services" + parent = "habitat/on-prem-builder/configure" + weight = 60 ++++ + +Chef Habitat On-Prem Builder uses MinIO to store Habitat artifact (`.hart`) files and PostgreSQL to store package and user metadata. + +You can configure Habitat Builder to run the backend components---MinIO and PostgreSQL---on separate nodes. + +## Configure node ports + +Because Habitat Builder services need to communicate across your network between the frontend and backend nodes, you need to open the following ports to these nodes to ensure your Habitat On-Prem Builder works correctly: + +- TCP 9638 - Habitat configuration gossip +- UDP 9638 - Habitat configuration gossip +- TCP 9636 - Builder API HTTP +- TCP 5432 - PostgreSQL +- TCP 9000 - MinIO +- TCP 11211 - Memcached + +## Deploy MinIO on a separate node + +Habitat Builder is configured using the `bldr.env` file, which contains all the information you need to set up MinIO and PostgreSQL. Follow these steps to configure the `bldr.env` file: + +1. If you don't already have it on your node, clone the [habitat-sh/on-prem-builder repository](https://github.com/habitat-sh/on-prem-builder/) or download and extract one of the [on-prem-builder releases](https://github.com/habitat-sh/on-prem-builder/releases). + +1. If your node previously ran Habitat On-Prem Builder components, run the [`uninstall.sh` script](https://github.com/habitat-sh/on-prem-builder/blob/main/uninstall.sh) to clean up your environment: + + ```bash + ./uninstall.sh + ``` + +1. Copy the [`bldr.env.sample` file](https://github.com/habitat-sh/on-prem-builder/blob/main/bldr.env.sample) and save it as `bldr.env`: + + ```bash + cp bldr.env.sample bldr.env + ``` + +1. Edit the `bldr.env` file with these settings: + + 1. Set `S3_ENABLED` and `ARTIFACTORY_ENABLED` to `false`. + + You can't use the MinIO server if you're using S3 or Artifactory directly. + + 1. List all frontend and backend nodes running Habitat Builder services using `HAB_BLDR_PEER_ARG` and the `--peer` option using the following format: + + ```shell + HAB_BLDR_PEER_ARG="--peer --peer --peer " + ``` + + Replace `` with a node IP address or hostname. + +1. Install MinIO by running the install script: + + ```bash + ./install.sh --install-minio + ``` + +1. Now that your Minio server is up and running on its own node, connect your frontend Habitat Builder nodes to the MinIO node. + + On your frontend nodes, set the `MINIO_ENDPOINT` in the `bldr.env` file to the node where the MinIO server is running. + +## Deploy PostgreSQL on a separate node + +Habitat Builder is configured using the `bldr.env` file, which contains all the information you need to set up MinIO and PostgreSQL. Follow these steps to configure the `bldr.env` file: + +1. If you don't already have it on your node, clone the [habitat-sh/on-prem-builder repository](https://github.com/habitat-sh/on-prem-builder/) or download and extract one of the [on-prem-builder releases](https://github.com/habitat-sh/on-prem-builder/releases). + +1. If your node previously ran Habitat On-Prem Builder components, run the [`uninstall.sh` script](https://github.com/habitat-sh/on-prem-builder/blob/main/uninstall.sh) to clean up your environment: + + ```bash + ./uninstall.sh + ``` + +1. Copy the [`bldr.env.sample` file](https://github.com/habitat-sh/on-prem-builder/blob/main/bldr.env.sample) and save it as `bldr.env`: + + ```bash + cp bldr.env.sample bldr.env + ``` + +1. Edit the `bldr.env` file with these settings: + + 1. Set `PG_EXT_ENABLED` to `false`. + + The datastore node can't use an externally hosted PostgreSQL, such as AWS RDS or Azure Database for PostgreSQL. + For details about opening the required ports, see the [scaling documentation](./scaling.md#deploying-new-front-ends). + + 1. List all frontend and backend nodes hosting builder services using `HAB_BLDR_PEER_ARG` and the `--peer` option using the following format: + + ```shell + HAB_BLDR_PEER_ARG="--peer --peer --peer " + ``` + + Replace `` with a node IP address or hostname. + +1. Install PostgreSQL by running the install script: + + ```bash + ./install.sh --install-postgresql + ``` + +1. Connect the frontend Builder nodes to the PostgreSQL datastore node. + + On your frontend Builder nodes, set `POSTGRES_HOST` in the `bldr.env` file to the node that's running the Habitat Builder PostgreSQL datastore. + +## More information + +For details about setting up and scaling the frontend, see [scaling Habitat Builder's frontend documentation](/habitat/on_prem_builder/configure/scale_frontend_nodes/). + +For information about managing resources with MinIO and PostgreSQL: + +- [Manage your MinIO artifact store](../manage/minio) +- [Manage Habitat Builder data stored with PostgreSQL](../manage/postgres) diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/install/_index.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/install/_index.md new file mode 100644 index 0000000000..35d116ee48 --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/install/_index.md @@ -0,0 +1,26 @@ ++++ +title = "Chef Habitat On-Prem Builder install overview" + +[menu] + [menu.habitat] + title = "Overview" + identifier = "habitat/on-prem-builder/install/install/overview" + parent = "habitat/on-prem-builder/install" + weight = 10 ++++ + +You can deploy Chef Habitat On-Prem Builder so that users authenticate using Chef Automate or another OAuth service. + +## System requirements + +Before you begin, review the [Habitat Builder system requirements](system_requirements). + +## Install guides + +To deploy Habitat On-Prem Builder, use the following guide: + +- [Install Habitat On-Prem Builder authenticating with another OAuth service](builder-oauth) + +## Workstation configuration + +- [Configure your workstation to connect to your Habitat Builder deployment](workstation) diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/install/builder_oauth.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/install/builder_oauth.md new file mode 100644 index 0000000000..0d12085851 --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/install/builder_oauth.md @@ -0,0 +1,227 @@ ++++ +title = "Install Chef Habitat On-Prem Builder with OAuth services" + +[menu] + [menu.habitat] + title = "Install Builder" + identifier = "habitat/on-prem-builder/install/o-auth" + parent = "habitat/on-prem-builder/install" + weight = 40 ++++ + +This page documents how to deploy Chef Habitat On-Prem Builder with a 3rd-party OAuth provider that provides authentication services. + +## Before you begin + +Before you begin, review [Habitat Builder's system requirements](../system_requirements). + +### Configure an OAuth provider + +Chef Habitat On-Prem Builder supports Azure AD (OpenID Connect), GitHub, GitLab (OpenID Connect), Okta (OpenID Connect), and Atlassian Bitbucket (cloud) OAuth providers for authentication. +You need to set up an OAuth application for your Chef Habitat On-Prem Builder instance. + +Before you begin, refer to the for the OAuth provider that you plan to use: + +- [Azure Active Directory](https://docs.microsoft.com/azure/active-directory/develop/active-directory-protocols-oauth-code) +- [GitHub](https://developer.github.com/apps/building-oauth-apps/authorization-options-for-oauth-apps/) +- [GitLab](https://docs.gitlab.com/ee/integration/oauth_provider.html) +- [Okta](https://developer.okta.com/authentication-guide/implementing-authentication/auth-code) +- [Bitbucket](https://confluence.atlassian.com/bitbucket/oauth-on-bitbucket-cloud-238027431.html) + +Follow the steps for your OAuth provider to create and configure your OAuth application. +The following steps show how to set up the OAuth application using GitHub as the identity provider: + +1. Create a new OAuth application in your OAuth provider, for example, [GitHub](https://github.com/settings/applications/new). + +1. Record the following OAuth configuration settings which you will use when define the `bldr.env` config file: + + - Authorization endpoint (for example, `https://github.com/login/oauth/authorize`) + - Token endpoint (for example, `https://github.com/login/oauth/access_token`) + - API endpoint (for example, `https://api.github.com/user`) + - Record the client ID and client secret. You'll use these for the `OAUTH_CLIENT_ID` and `OAUTH_CLIENT_SECRET` environment variables. + +For more details on OAuth endpoints, see the Internet Engineering Task Force (IETF) RFC 6749, [The OAuth 2.0 Authorization Framework](https://datatracker.ietf.org/doc/html/rfc6749#section-3.2). + +### Optional: Prepare your filesystem + +You might need substantial storage for packages, so make sure you have enough free space on your filesystem. + +The package artifacts are stored in your MinIO instance by default, typically at the following location: `/hab/svc/builder-minio/data`. If you need more storage, create a mount at `/hab` and point it to your external storage. +You don't need to do this if you already have enough free space. + +If you want to use Artifactory instead of MinIO for object storage, see the [Artifactory documentation](/habitat/on_prem_builder/configure/artifactory). + +### Get an SSL certificate + +By default, Chef Habitat On-Prem Builder exposes the web UI and API through HTTP. +This setup is easier for evaluation, but for a secure and permanent installation you should enable SSL on these endpoints. + +To prepare, get an SSL certificate. +You can use a self-signed certificate, but if you do, you need to install the certificate in the trusted chain on client machines that use the Chef Habitat On-Prem Builder UI or APIs. + +The following example command generates a self-signed certificate with OpenSSL: + +```bash +sudo openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /etc/ssl/private/ssl-certificate.key -out /etc/ssl/certs/ssl-certificate.crt +``` + +The certificate files must be named `ssl-certificate.key` and `ssl-certificate.crt`. If you get the certificate from another source, rename the files to these names. Place both files in the same folder as the `install.sh` script. The install process uploads them to the Chef Habitat supervisor. + +{{< note >}} + +You can also use the `SSL_CERT_FILE` environment variable to point to the certificate on client machines when using the `hab` client, for example: + +```bash +SSL_CERT_FILE=ssl-certificate.crt hab pkg search -u https://localhost +``` + +{{< /note >}} + +### Prerequisites for airgapped environments + +If you're installing Chef Habitat On-Prem Builder in an airgapped environment, follow the steps below to download and install Chef Habitat and Chef Habitat packages in the airgapped environment. + +With an internet-connected computer, follow these steps: + +1. Download the [zip archive of the on-prem-builder repository](https://github.com/habitat-sh/on-prem-builder/archive/master.zip): + + ```bash + curl -LO https://github.com/habitat-sh/on-prem-builder/archive/master.zip + ``` + +1. Download the Chef Habitat [CLI tool](https://packages.chef.io/files/stable/habitat/latest/hab-x86_64-linux.tar.gz): + + ```bash + curl -Lo hab.tar.gz https://packages.chef.io/files/stable/habitat/latest/hab-x86_64-linux.tar.gz + ``` + +1. Create the Habitat Builder package bundle from the Builder seed lists and download the packages: + + ```bash + sudo hab pkg install habitat/pkg-sync --channel LTS-2024 + + export DOWNLOAD_DIR=/path/to/download/directory + + hab pkg exec habitat/pkg-sync pkg-sync \ + --channel stable \ + --package-list builder \ + --generate-airgap-list + + hab pkg download \ + --target x86_64-linux \ + --channel stable \ + --file package_list_x86_64-linux.txt \ + --download-directory ${DOWNLOAD_DIR}/builder_packages + ``` + +1. Archive the download directory, then transfer and extract it on the Linux system where you will deploy Builder in the airgapped environment. + +In the airgapped environment, complete these steps: + +1. From the archive, install the `hab` binary somewhere in the system $PATH and ensure it has execute permissions: + + ```bash + sudo chmod 755 /usr/bin/hab + sudo hab + ``` + + Read and accept the license. + +1. Import the public package signing keys from the downloaded Builder package bundle: + + ```bash + export UNZIP_DIR=/some/base/unzip/directory + + for file in $(ls ${UNZIP_DIR}/builder_packages/keys/*pub); do + cat $file | sudo hab origin key import + done + ``` + +1. Create a Habitat artifact cache directory, place the Builder `*.hart` packages into that directory and then pre-install the Builder Services: + + ```bash + sudo mkdir -p /hab/cache/artifacts + sudo mv ${UNZIP_DIR}/builder_packages/artifacts/*hart /hab/cache/artifacts + sudo hab pkg install /hab/cache/artifacts/habitat-builder*hart + ``` + +1. Pre-install the Habitat Supervisor and its dependencies: + + ```bash + sudo hab pkg install --binlink --force /hab/cache/artifacts/core-hab-*hart + ``` + +## Configure Chef Habitat On-Prem Builder + +Chef Habitat On-Prem Builder is configured with a `bldr.env` file. Follow these steps to create and edit this file: + +1. On the machine where you want to install Chef Habitat On-Prem Builder, clone the [habitat-sh/on-prem-builder repository](https://github.com/habitat-sh/on-prem-builder/) or download a release from the [GitHub release page](https://github.com/habitat-sh/on-prem-builder/releases). + +1. In the repository root create a copy of the sample environment file: + + ```bash + cp bldr.env.sample bldr.env + ``` + +1. Open `bldr.env` in a text editor and update the values as needed. + + To configure your OAuth provider setting, enter the following: + + 1. Set `APP_URL` to the IP address or URL of your Habitat Builder deployment :`http:///`. Use `https` if you plan to enable SSL: `https:///`. + 1. Set `OAUTH_REDIRECT_URL` to the callback URL: `http:///`. You must include a trailing `/` with the URL. Specify `https` instead of `http` if you plan to enable SSL. + 1. Set `OAUTH_CLIENT_ID` and `OAUTH_CLIENT_SECRET` to the OAuth client ID and client secret. + + Optional: + + - To help improve Chef Habitat, you can set `ANALYTICS_ENABLED` to `true` and optionally provide your company name. + +## Install Chef Habitat On-Prem Builder + +Follow these steps: + +1. Run the install script: + + ```bash + ./install.sh + ``` + + If the installation succeeds, you should see output similar to the following, showing that the Chef Habitat On-Prem Builder services are loaded: + + ```shell + hab-sup(AG): The habitat/builder-datastore service was successfully loaded + hab-sup(AG): The habitat/builder-minio service was successfully loaded + hab-sup(AG): The habitat/builder-memcached service was successfully loaded + hab-sup(AG): The habitat/builder-api service was successfully loaded + hab-sup(AG): The habitat/builder-api-proxy service was successfully loaded + ``` + +1. Optional: Check the status of all services: + + ```bash + hab svc status + ``` + + It may take a few seconds for all services to start. + If any services aren't in the `up` state, see the [troubleshooting documentation](troubleshooting). + +## MinIO web UI + +Chef Habitat On-Prem Builder stores package artifacts in [MinIO](https://github.com/minio/minio). +By default, the MinIO instance is available on port 9000 or on the port you specified in your `bldr.env` file. +You can verify that the MinIO UI is available and log in with the credentials from your `bldr.env` file. +A bucket for storing artifacts should already exist. + +## Chef Habitat On-Prem Builder web UI + +After all services are running, the Chef Habitat On-Prem Builder UI is available at the configured hostname or IP address. + +Go to `http:///#/sign-in` to access the Chef Habitat On-Prem Builder UI. + +You can now sign in using your configured OAuth provider. + +## Next steps + +After you've deployed Habitat Builder: + +- [Configure your workstation to connect to your Habitat Builder deployment](../workstation). +- [Bootstrap the core origin packages](/habitat/on_prem_builder/packages/bootstrap_core_packages). diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/install/system_requirements.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/install/system_requirements.md new file mode 100644 index 0000000000..04757c3bd8 --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/install/system_requirements.md @@ -0,0 +1,41 @@ ++++ +title = "Habitat Builder system requirements" + +[menu] + [menu.habitat] + title = "System requirements" + identifier = "habitat/on-prem-builder/install/install/system requirements" + parent = "habitat/on-prem-builder/install" + weight = 20 ++++ + +See the following sections for Chef Habitat On-Prem Builder's requirements. + +## Requirements + +- Deploy Habitat Builder on a [Linux distribution supported by Habitat](/habitat/install_habitat/#chef-habitat-for-linux). +- The Linux OS must support the `systemd` process manager. +- You can deploy on bare metal, a VM, or a container image. +- Match CPU and RAM to your deployment purpose: + - Use 2 CPUs and 4 GB RAM for trial deployments. + - Use 16 CPUs and 32 GB RAM for production deployments. +- Provide enough free disk space: + - 2 GB for the baseline Chef Habitat On-Prem Builder services, + - 15 GB or more for the latest Chef Habitat On-Prem Builder core packages, + - 30 GB or more to download and expand the core package bootstrap in the volume containing `/tmp`. + + Recommended disk space: + - 50 GB for trial deployments. + - 100 GB for production deployments. +- Outbound network (HTTPS) connectivity to the WAN is required for the initial install. +- Inbound network connectivity from the LAN (HTTP/HTTPS) is required for internal clients to access Chef Habitat On-Prem Builder. This is port 80 or port 443 if you plan to enable SSL. +- An OAuth2 authentication provider is required. Chef Automate v2, Azure AD, GitHub, GitHub Enterprise, GitLab, Okta, and Bitbucket (cloud) are verified. You can request support for additional providers. + +## Optional: Memory filesystem storage + +Follow these guidelines for filesystem storage: + +- Chef Habitat On-Prem Builder needs substantial storage space for packages. Make sure your filesystem has enough free space. +- By default, Chef Habitat On-Prem Builder stores package artifacts in a MinIO instance, typically at `/hab/svc/builder-minio/data`. +- If you need more storage, create a mount at `/hab` and point it to your external storage. This isn't required if you already have enough free space. +- To use Artifactory instead of MinIO for object storage, see the [Habitat On-Prem Builder and Artifactory](/habitat/on_prem_builder/configure/artifactory/) documentation. diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/install/workstation.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/install/workstation.md new file mode 100644 index 0000000000..faa85685af --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/install/workstation.md @@ -0,0 +1,45 @@ ++++ +title = "Connect your workstation to your Chef Habitat On-Prem Builder deployment" + +[menu] + [menu.habitat] + title = "Connect your workstation to Builder" + identifier = "habitat/on-prem-builder/install/workstation" + parent = "habitat/on-prem-builder/install" + weight = 50 + ++++ + +Follow the steps below to configure your workstation to connect with your Chef Habitat On-Prem Builder deployment. + +## Before you begin + +Before you begin, you'll need to set or create an authentication token in your Habitat Builder deployment. + +If you don't already have a token, follow these steps to generate one: + +1. In the top right corner of your Habitat On-Prem Builder site, select your Gravatar icon, then select **Profile**. +1. On the profile page, generate your access token and save it securely. + +## Configure your workstation + +To configure your workstation to connect to your deployment of Chef Habitat On-Prem Builder, set the following environment variables: + +1. Set `HAB_BLDR_URL` to the URL of your Chef Habitat On-Prem Builder deployment. + For example: + + ```shell + export HAB_BLDR_URL=https://bldr.example.com/bldr/v1/ + ``` + +1. Set `HAB_AUTH_TOKEN` to your authentication token: + + ```shell + export HAB_AUTH_TOKEN= + ``` + +1. If your Chef Habitat On-Prem Builder deployment uses SSL with a self-signed or untrusted certificate, set `SSL_CERT_FILE` to the correct certificate when connecting to your Habitat Builder. + + ```shell + export SSL_CERT_FILE=path/to/ssl-certificate.crt + ``` diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/_index.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/_index.md new file mode 100644 index 0000000000..afb52b7ace --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/_index.md @@ -0,0 +1,17 @@ ++++ +title = "Manage Habitat On-Prem Builder" + +[menu] + [menu.habitat] + title = "Overview" + identifier = "habitat/on-prem-builder/manage/overview" + parent = "habitat/on-prem-builder/manage" + weight = 10 ++++ + +Use the following pages to manage your Habitat Builder deployment and data: + +- [Manage packages data stored with MinIO](minio). +- [Manage package and user data stored with PostgreSQL](postgres). +- [Rotate SSL certificates](ssl_cert_rotation). +- [Upgrade your Chef Habitat On-Prem Builder deployment](upgrade). diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/minio.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/minio.md new file mode 100644 index 0000000000..0addb49739 --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/minio.md @@ -0,0 +1,56 @@ ++++ +title = "Manage your MinIO artifact store" + +[menu] + [menu.habitat] + title = "MinIO" + identifier = "habitat/on-prem-builder/manage/minio" + parent = "habitat/on-prem-builder/manage" + weight = 20 ++++ + +[MinIO](https://min.io/) is an open source object storage server. +Chef Habitat On-Prem Builder uses MinIO to store Habitat artifact (`.hart`) files. + +## Habitat Builder data overview + +Habitat Builder's data is lightweight, so backup and disaster recovery strategies are straightforward. +Builder has two types of data you should back up in case of a disaster: + +- [Habitat package and user metadata stored with PostgreSQL](../postgres#postgresql-data-backups). +- Habitat artifacts (`.hart`) files stored by MinIO. + +Chef Habitat On-Prem Builder supports only MinIO artifact repositories. + +Ideally you should run the entire On-Prem Builder cluster backup at the same time. +However, because Builder stores only metadata and artifacts, you have some flexibility in the timing of your backup operations. + +## Backup Habitat artifacts stored by MinIO + +Backing up MinIO data is similar to performing a filesystem backup. +Because MinIO stores files on the filesystem (unless you're using a non-standard configuration), you can use any filesystem backup strategy, such as disk snapshots, data mirroring, or `rsync`. +MinIO also provides the [MinIO client](https://docs.min.io/docs/minio-client-quickstart-guide.html), which offers many features, including the ability to mirror a bucket to another location on the filesystem or to a remote S3 bucket. + +Don't directly or manually manipulate files within MinIO's buckets while MinIO could be performing I/O. +Always use the MinIO client to manage MinIO data. + +Because backup operations can vary depending on your environment, you may need to adjust these steps. +Use the following backup example as a starting point: + +1. Shut down the API to make sure there are no active transactions (optional but recommended): + + ```shell + hab svc stop habitat/builder-api + ``` + +1. Mirror MinIO data to an AWS S3 bucket: + + ```shell + mc mirror + ``` + + Or, mirror to a different part of the filesystem, such as an NFS mount, and then take snapshots: + + ```shell + mc mirror + ``` diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/postgres.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/postgres.md new file mode 100644 index 0000000000..2791ea0baa --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/postgres.md @@ -0,0 +1,125 @@ ++++ +title = "Manage Habitat Builder data stored by PostgreSQL" + +[menu] + [menu.habitat] + title = "PostgreSQL" + identifier = "habitat/on-prem-builder/manage/PostgreSQL" + parent = "habitat/on-prem-builder/manage" + weight = 30 ++++ + +This page describes how to back up Habitat Builder user and package data that's managed by PostgreSQL. + +## Habitat Builder data overview + +Habitat Builder's data is lightweight, so backup and disaster recovery strategies are straightforward. +On-Prem Builder has two types of data you should back up in case of a disaster: + +- PostgreSQL package and user metadata +- [MinIO Habitat artifacts](../minio#minio-artifact-backups) + +Ideally, coordinate the backup of the entire On-Prem Builder cluster at the same time. +However, because Habitat Builder stores only metadata and artifacts, you have some flexibility in the timing of your backup operations. +If a package's metadata is missing from PostgreSQL, you can repopulate it by re-uploading the package with the `--force` flag, for example: + +```shell +hab pkg upload -u --force +``` + +## Back up the PostgreSQL database + +Backing up Builder's PostgreSQL database is the same as backing up any PostgreSQL database. +The process uses [pg_dump](https://www.postgresql.org/docs/11/app-pgdump.html). +If you already have a backup strategy for other production PostgreSQL instances, apply that pattern to the `builder` database. +To back up your `builder` database manually, follow these steps: + +1. Optional but recommended: Shut down the API to make sure there are no active transactions: + + ```shell + hab svc stop habitat/builder-api + ``` + +1. Switch to the `hab` user: + + ```shell + sudo su - hab + ``` + +1. Find your PostgreSQL password: + + ```shell + sudo cat /hab/svc/builder-api/config/config.toml + ``` + +1. Export the password as an environment variable: + + ```shell + export PGPASSWORD= + ``` + +1. Create a backup of the database: + + ```shell + /hab/pkgs/core/postgresql///bin/pg_dump --file=builder.dump --format=custom --host= --dbname=builder + ``` + +1. Start the API and verify it's running: + + ```shell + sudo hab svc start habitat/builder-api + ``` + +After the backup finishes, you'll find the `builder.dump` file on your filesystem. +Move and store this file according to your organization's policies. +Store the backup in a remote location---either physically or virtually---so you can access it in a disaster scenario. +For example, you can use an AWS bucket or Azure storage. +Use the same backup strategy you use for your other databases. + +## Restore the PostgreSQL database + +Restoring a `builder` database is the same as restoring any other PostgreSQL database. +If you already have a restoration strategy, use it to restore your `builder` database. +To restore your `builder` database manually, follow these steps: + +1. Switch to the `hab` user: + + ```shell + sudo su - hab + ``` + +1. Find your PostgreSQL password: + + ```shell + sudo cat /hab/svc/builder-api/config/config.toml + ``` + +1. Export the password as an environment variable: + + ```shell + export PGPASSWORD= + ``` + +1. Create a new database called `builder` (if needed): + + ```shell + /hab/pkgs/core/postgresql///bin/createdb -w -h -p -U hab builder + ``` + + If your version of PostgreSQL doesn't have the `createdb` binary, connect to the database and run the create database command manually. + +1. Verify connectivity to the new database instance: + + ```shell + /hab/pkgs/core/postgresql///bin/psql --host= --dbname=builder + ``` + +1. Restore the contents of the `builder.dump` backup file into the `builder` database: + + ```shell + /hab/pkgs/core/postgresql///bin/pg_restore --host= --dbname=builder builder.dump + ``` + +1. Start the Habitat On-Prem Builder services. + +Your database data should now be restored and ready for use! diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/ssl_cert_rotation.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/ssl_cert_rotation.md new file mode 100644 index 0000000000..58198736a5 --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/ssl_cert_rotation.md @@ -0,0 +1,42 @@ ++++ +title = "Rotate Habitat Builder's SSL certificates" + +[menu.habitat] + title = "Rotate SSL certs" + identifier = "habitat/on-prem-builder/manage/SSL certs" + parent = "habitat/on-prem-builder/manage" + weight = 40 ++++ + +Chef Habitat On-Prem Builder's web frontend runs on NGINX using the `habitat/builder-api-proxy` service. +The NGINX config for this service loads the SSL certificate and key from `/hab/svc/builder-api-proxy/files`. + +## Rotate the SSL certificate and key + +There's really a few simple commands to run in order to rotate your key. + +1. Rename your SSL certificate and key file to the names required by the builder-api-proxy service: + + ```shell + cp ssl-certificate.crt + cp ssl-certificate.key + ``` + + The certificate and key files must be named `ssl-certificate.crt` and `ssl-certificate.key`. + +1. Upload the certificate and key files to the builder service: + + ```shell + hab file upload "builder-api-proxy.default" "$(date +%s)" ./ssl-certificate.crt + hab file upload "builder-api-proxy.default" "$(date +%s)" ./ssl-certificate.key + ``` + +1. Restart the builder-api-proxy service: + + ```shell + hab svc stop habitat/builder-api-proxy && hab svc start habitat/builder-api-proxy + ``` + + This puts the updated files into the appropriate path and restarts NGINX so that it's using your new certificate and key. + +You should now be able to verify through your browser or with the `openssl s_client -connect` command that Habitat Builder has an updated certificate. diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/upgrade.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/upgrade.md new file mode 100644 index 0000000000..616410c0c7 --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/upgrade.md @@ -0,0 +1,35 @@ ++++ +title = "Upgrade your Chef Habitat On-Prem Builder deployment" + +[menu] + [menu.habitat] + title = "Upgrade Builder" + identifier = "habitat/on-prem-builder/manage/upgrade" + parent = "habitat/on-prem-builder/manage" + weight = 50 ++++ + +Chef Habitat On-Prem Builder services don't upgrade automatically. +To upgrade the services, use the uninstall script to stop, unload, and remove them. + +{{< note >}} + +The uninstall script doesn't remove user data, so you can uninstall and reinstall the Habitat Builder services without losing data. + +{{< /note >}} + +To upgrade Chef Habitat On-Prem Builder, follow these steps: + +1. Clone the [`habitat-sh/on-prem-builder`](https://github.com/habitat-sh/on-prem-builder) repository on the computer running Habitat On-Prem Builder. + +1. Uninstall all Habitat Builder services by running the [uninstall script](https://github.com/habitat-sh/on-prem-builder/blob/main/uninstall.sh): + + ```shell + sudo ./uninstall.sh + ``` + +1. After the services are uninstalled, reinstall them by running the [`install.sh` script](https://github.com/habitat-sh/on-prem-builder/blob/main/install.sh): + + ```shell + ./install.sh + ``` diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/_index.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/_index.md new file mode 100644 index 0000000000..add4208a14 --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/_index.md @@ -0,0 +1,42 @@ ++++ +title = "Chef Habitat origins" + +[menu] + [menu.habitat] + title = "Overview" + identifier = "habitat/on-prem-builder/origins/overview" + parent = "habitat/on-prem-builder/origins" + weight = 10 ++++ + +An origin is a unique namespace in Chef Habitat Builder where you can store, share, and build packages. +Once created, you can'tt rename an origin, but you can delete or transfer it. +For example, the _core_ origin contains foundational packages managed and versioned by the core Chef Habitat maintainers. + +You can create origins in an Habitat On-Prem Builder deployment. +[Chef's public Habitat Builder](https://bldr.habitat.sh) doesn't support creating new origins. + +You can join existing origins by invitation or create your own origins in an Habitat On-Prem Builder deployment. + +## Chef-owned origins + +Progress Chef maintains the following origins: + +- **core**: Hosts packages for common dependencies and compilers maintained by Progress Chef. +- **chef**: Hosts packages for Chef products like Chef Infra Client, Chef InSpec, and Chef Automate. +- **chef-platform**: Hosts packages for Chef 360 Platform skills. +- **habitat**: Hosts packages required for an Habitat On-Prem Builder deployment. + +## Origin user guides + +See the following user guides for managing Chef Habitat origins: + +- [Create an origin](create_an_origin) +- [Origin keys](origin_keys) +- [Origin settings](origin_settings) +- [Origin role-based access control](rbac) + +## More information + +- [Manage packages in Habitat On-Prem Builder](../packages/) +- [Habitat packages](../packages/) diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/create_an_origin.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/create_an_origin.md new file mode 100644 index 0000000000..0f0fccc210 --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/create_an_origin.md @@ -0,0 +1,54 @@ ++++ +title = "Create an origin" + +[menu] + [menu.habitat] + title = "Create an origin" + identifier = "habitat/on-prem-builder/origins/create" + parent = "habitat/on-prem-builder/origins" + weight = 20 ++++ + +You can create origins in a private Habitat Builder deployment using either the Habitat Builder UI or the `hab` CLI. +[Chef's public Habitat Builder](https://bldr.habitat.sh) doesn't support creating new origins. + +## Create an origin in Chef Habitat Builder + +To create an origin in your Chef Habitat Builder deployment, follow these steps: + +1. In Habitat Builder, select **My Origins** in the left navigation menu. + +1. On the **My Origins** page, select **Create origin** to open the **Create New Origin** form. + +1. Enter a unique name for your origin. Chef Habitat requires origin names to be unique. Examples of origin names include team names, user names, or abstract concepts. + +1. Choose a default privacy setting 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: + + - Public packages are visible to and usable by anyone. + - Private packages are visible to and usable only by users with origin membership. + +1. Select **Save and Continue**. + + Habitat Builder performs the following actions: + + - Creates your origin. + - Creates an [origin key pair](../origin_keys). + - Redirects you to the origin page. + + ![Origin successfully created](/images/habitat/create-origin-done.png) + +## Create an origin with the Chef Habitat CLI + +Before you create an origin, make sure your [workstation is configured](../../install/workstation) to connect to your private Habitat Builder deployment. + +To create an origin with the `hab` CLI, use the [`hab origin create`](/habitat/habitat_cli/#hab-origin-create) command. For example: + +- ```bash + hab origin create + ``` + +This command creates an origin on the Chef Habitat Builder site. + +To create a key pair for your origin, see the [origin keys](../origin_keys) documentation. diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/origin_keys.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/origin_keys.md new file mode 100644 index 0000000000..fa70f8032d --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/origin_keys.md @@ -0,0 +1,185 @@ ++++ +title = "Habitat origin keys" + +[menu] + [menu.habitat] + title = "Origin keys" + identifier = "habitat/on-prem-builder/origins/keys" + parent = "habitat/on-prem-builder/origins" + weight = 30 ++++ + +When you create an origin, Chef Habitat On-prem 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. + +Chef Habitat uses origin keys in the following ways: + +- 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 On-prem Builder, 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. + +## Prerequisites + +- [Download and installed the Chef Habitat CLI](/habitat/install_habitat/). +- [Create a Chef Habitat On-prem Builder account](/habitat/builder_account/). +- [Generate a personal access token](/habitat/builder_profile/#create-a-personal-access-token). +- [Create an origin with `hab origin create` or join an origin by invitation](../create_an_origin). + +## Key access + +All Chef Habitat On-prem 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 origin members with the administrator or owner roles can view or download the origin private key, or change the origin key pair. + +| Keys Actions | Read-Only | Member | Maintainer | Administrator | Owner | +|---------|-------|-------|-------|-------|-------| +| View keys | Y | Y | Y | Y | Y | +| Add/Update/Delete keys | N | N | N | Y | Y | + +## Key filename format + +Chef Habitat On-prem Builder origin keys use the following format: + +- Public key: `-.pub` +- Private key or signing key: `-.sig.key` + +For example, in: + +```shell +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. + +## Get origin keys + +When you create an origin, Chef Habitat On-prem Builder automatically generates an origin key pair and saves both keys. To view an origin's keys on Chef Habitat On-prem Builder, navigate to the origin and select **Keys**. +Anyone can view and download an origin's public keys, but only origin owners and administrators can view or download an origin private key, or change the origin key pair. + +![Viewing your origin keys](/images/habitat/origin-keys.png) + +### Download origin keys + +To download your private or public origin key, select {{< icons class="material-symbols-outlined icon-filled" icon="download_2" >}} **Download this key** under the **Actions** heading. + +### Upload origin keys + +To upload a public or private origin key in Chef Habitat On-prem Builder, select either **Upload a private key** or **Upload a public key** and paste your key into the dialog box that appears. + +## Manage origin keys with the CLI + +Run Chef Habitat CLI commands from your local environment or from within the Chef Habitat Studio. + +For more information, see the [`hab origin key` CLI documentation](/habitat/habitat_cli/#hab-origin-key). + +### 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. + +#### Find your origin keys in your local environment + +On Windows: + +```PowerShell +Get-ChildItem C:\hab\cache\keys +``` + +On Linux or macOS: + +```bash +ls -la ~/.hab/cache/keys +``` + +#### Find your existing origin keys from inside of the Chef Habitat Studio + +On Windows: + +```powershell +Get-ChildItem C:\hab\cache\keys +``` + +On Linux or macOS: + +```bash +ls -la /hab/cache/keys +``` + +### Generate origin keys with the CLI + +When you create an origin in Chef Habitat On-prem Builder, 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`](/habitat/hab_setup/) to generate your first origin key pair as part of setting up the `hab` CLI. +- Use the `hab origin key generate` command to create an key pair for an origin created with the `hab origin create` command + +To create an origin key with the `hab` CLI, run the [`hab origin key generate` command](/habitat/habitat_cli/#hab-origin-key-generate): + +```shell +hab origin key generate +``` + +### Download origin keys with the CLI + +To download your public origin key using the command line, use [`hab origin key download` command](/habitat/habitat_cli/#hab-origin-key-download): + +```shell +hab origin key download +``` + +### Upload origin keys with the CLI + +Creating an origin with the `hab origin create` command registers the origin on Chef Habitat On-prem 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 On-prem Builder. + +- Only origin members with the administrator and owner roles can upload new keys to an origin. +- Habitat On-prem Builder requires the public origin key to upload artifacts for that origin, so you'll need to upload it. +- Habitat On-prem 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 origin key upload` command](/habitat/habitat_cli/#hab-origin-key-upload): + +```shell +hab origin key upload +``` + +Upload the origin private key: + +```shell +hab origin key upload --secret +``` + +Upload both origin keys at the same time: + +```shell +hab origin key upload --secfile --pubfile +``` + +### Import origin keys with the CLI + +Use [`hab origin key import`](/habitat/habitat_cli/#hab-origin-key-import) to read the key from a standard input stream into Chef Habitat On-prem Builder: + +```shell +hab origin key import +hab origin key import +curl | hab origin key import +``` + +#### Troubleshoot origin key import + +On a macOS, you may encounter an upload failure. +Follow these steps 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`. For example: + + ```bash + export SSL_CERT_FILE=/usr/local/etc/openssl/cert.pem + ``` + + After you've added this variable to your shell configuration, reinitialize the shell configuration. For example: + + ```bash + source ~/.bashrc + ``` diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/origin_settings.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/origin_settings.md new file mode 100644 index 0000000000..a094bae467 --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/origin_settings.md @@ -0,0 +1,101 @@ ++++ +title = "Habitat origin settings" + +[menu] + [menu.habitat] + title = "Origin settings" + identifier = "habitat/on-prem-builder/origins/settings" + parent = "habitat/on-prem-builder/origins" + weight = 40 ++++ + +The **Settings** tab for an origin lets you view and manage default package settings and origin secrets. + +Every origin member can view the origin's settings, but only origin administrators and owners can add, update, or delete settings. + +| Settings actions | Read-only | Member | Maintainer | Administrator | Owner | +|------------------|-----------|--------|------------|---------------|-------| +| View settings | Y | Y | Y | Y | Y | +| Add/update/delete settings | N | N | N | Y | Y | +| View secrets | N | N | Y | Y | Y | +| Add/update/delete secrets | N | N | N | Y | Y | + +![The administrator or owner's view of the origin settings tab with a public default package setting and a saved origin secret](/images/habitat/origin-secrets.png) + +## Default package settings + +The **Default Package Settings** define the default visibility of a package's build artifacts (`.hart` files) in an origin: + +- **Public packages** are visible in search results and can be used by any Chef Habitat Builder user. +- **Private packages** don't appear in search results and are available only to users with origin membership. + +Packages can have different visibility settings from the origin to which they belong. + +To change the origin's default visibility settings, select the origin in Habitat Builder, go to **Settings**, and select either **Public artifacts** or **Private artifacts**. + +## Origin secrets + +Origin secrets let you encrypt and store secrets as environment variables. These secrets are useful for plans that require access to protected resources at build time, such as private source-code repositories or cloud storage providers. + +Origin secrets are retained by the origin and are available for any of that origin's packages. The secrets in your local environment are encrypted with an origin encryption key. Only Chef Habitat Builder can read encrypted origin secrets. + +Every origin member can view an origin's secrets, but only origin administrators and owners can add, update, or delete them. You can find **Origin Secrets** at the bottom of the **Settings** tab (Builder > Origin > Settings > 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 to interact with origin secrets is through the Chef Habitat CLI. + +#### List secrets + +To list all secrets in an origin, run: + +```bash +hab origin secret list --origin +``` + +#### Set origin secrets as environment variables + +Add your origin secrets as environment variables in your local environment: + +```bash +export HAB_ORIGIN= +export HAB_AUTH_TOKEN= +hab origin secret list +``` + +#### Save an origin secret + +To save an origin secret, give the secret a name and a key value: + +```bash +hab origin secret upload AWS_ACCESS_KEY_ID +hab origin secret upload AWS_SECRET_ACCESS_KEY +``` + +The output should look similar to this: + +```bash +$ 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, run: + +```bash +hab origin secret delete AWS_ACCESS_KEY_ID +hab origin secret delete AWS_SECRET_ACCESS_KEY +``` + +## More information + +- See [Using origin secrets in plans](/habitat/plan_writing/#buildtime-workflow) for guidance on using origin secrets. +- See the [`hab origin secret`](/habitat/habitat_cli/#hab-origin-secret) CLI documentation for more information on these commands. diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/rbac.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/rbac.md new file mode 100644 index 0000000000..7a489c6658 --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/rbac.md @@ -0,0 +1,168 @@ ++++ +title = "Configure origin membership and role-based access control" + +[menu] + [menu.habitat] + title = "Origin membership and RBAC" + identifier = "habitat/on-prem-builder/origins/rbac" + parent = "habitat/on-prem-builder/origins" + weight = 50 ++++ + +You can use role-based access control (RBAC) to assign specific levels of access to each user that belongs to an origin. + +When you join an origin, Chef Habitat Builder assigns you the _read-only_ role, and when you create an origin, it assigns you the _owner_ role. These roles are linked to your personal access token. An owner or administrator can update a user's role. + +## Prerequisites + +- [Download and install the Chef Habitat CLI](/habitat/install_habitat/) +- A Chef Habitat On-Prem Builder account +- A personal access token for On-Prem Builder +- [Create an origin](../create_an_origin) or accept an invitation to an existing origin +- [Get origin keys](../origin_keys) + +## Origin roles + +Chef Habitat Builder has the following origin roles and permissions: + +Read-Only + +- Can view packages, channels, origin membership, invitations, member roles, settings, and integrations. +- Can't upload, promote, or modify packages, channels, keys, settings, or integrations. +- Can't manage origin membership, roles, or secrets. + +Member + +- Inherits all Read-Only permissions. +- Can upload packages to the unstable channel and trigger build jobs in unstable. +- Can't promote packages or modify channels, keys, settings, or integrations. +- Can't manage origin membership, roles, or secrets. + +Maintainer + +- Inherits all Member permissions. +- Can promote packages, add/update/delete channels, and manage integrations. +- Can't manage origin keys, membership roles, or secrets. + +Administrator + +- Inherits all Maintainer permissions. +- Can manage origin keys, membership roles, and secrets. +- Can't transfer or delete the origin. + +Owner + +- Has full permissions, including the ability to transfer or delete the origin. +- Can perform all actions available to Administrators and more. + +Also, see the following table of role permissions: + +| Action | Read-Only | Member | Maintainer | Administrator | Owner | +| -------------------------------- | --------- | ------ | ---------- | ------------- | ----- | +| **Packages** | | | | | | +| View packages | Y | Y | Y | Y | Y | +| Upload packages to `unstable` | N | Y | Y | Y | Y | +| Promote packages from `unstable` | N | N | Y | Y | Y | +| **Channels** | | | | | | +| View channels | Y | Y | Y | Y | Y | +| Add/Update/Delete channels | N | N | Y | Y | Y | +| **Origin Keys** | | | | | | +| View keys | Y | Y | Y | Y | Y | +| Add/Update/Delete keys | N | N | N | Y | Y | +| **Origin Membership** | | | | | | +| View origin membership | Y | Y | Y | Y | Y | +| View invitations | Y | Y | Y | Y | Y | +| Send Invitations | N | N | Y | Y | Y | +| Revoke Invitations | N | N | Y | Y | Y | +| **Member Roles** | | | | | | +| View member roles | Y | Y | Y | Y | Y | +| Update member roles | N | N | N | Y | Y | +| **Origin Settings** | | | | | | +| View settings | Y | Y | Y | Y | Y | +| Add/Update/Delete settings | N | N | N | Y | Y | +| **Origin Secrets** | | | | | | +| View secrets | N | N | N | Y | Y | +| Add/Update/Delete secrets | N | N | N | Y | Y | +| **Cloud Integrations** | | | | | | +| View integrations | Y | Y | Y | Y | Y | +| Add/Update/Delete integrations | N | N | Y | Y | Y | +| **Ownership** | | | | | | +| Transfer origin | N | N | N | N | Y | +| Delete origin | N | N | N | N | Y | + +### Manage origin members + +You can use the `hab` CLI to manage and view users' roles in an origin. You can also view users' roles and invite users in Habitat Builder. + +#### Invite members + +Manage Chef Habitat Builder origin membership with the Chef Habitat CLI, using the [`hab origin invitations`](/habitat/habitat_cli/#hab-origin-invitations) command. + +All Chef Habitat Builder users can accept, ignore, and see invitations for their accounts. + +View origin invitations: + +```bash +hab origin invitations list +``` + +Accept origin invitations: + +```bash +hab origin invitations accept +``` + +Ignore origin invitations: + +```bash +hab origin invitations ignore +``` + +Send origin membership invitations: + +```bash +hab origin invitations send +``` + +Origin administrators and owners can see all pending origin membership invitations: + +```bash +hab origin invitations pending +``` + +Origin administrators and owners can rescind an origin membership invitation: + +```bash +hab origin invitations rescind +``` + +### Transfer origin ownership + +Origin owners can transfer origin ownership to another member with the [`hab origin transfer` subcommand](/habitat/habitat_cli/#hab-origin-transfer): + +```bash +hab origin transfer [OPTIONS] +``` + +#### Manage membership roles + +You can see and set a member's role using the `hab origin rbac` CLI subcommands. +You can also see the list of origin members in an origin's **Members** tab. + +The [`hab origin rbac`](/habitat/habitat_cli/#hab-origin-rbac) command syntax is: + +```bash +hab origin rbac +``` + +The syntax for the `show` subcommand is: + +```bash +hab origin rbac show --origin +``` + +The syntax for the `set` subcommand is: + +```bash +hab origin rbac set [FLAGS] [OPTIONS] --origin +``` diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/packages/_index.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/packages/_index.md new file mode 100644 index 0000000000..14ed45f818 --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/packages/_index.md @@ -0,0 +1,15 @@ ++++ +title = "Manage Habitat packages in Habitat On-Prem Builder" + +[menu] + [menu.habitat] + title = "Overview" + identifier = "habitat/on-prem-builder/packages/overview" + parent = "habitat/on-prem-builder/packages" + weight = 10 ++++ + +Use the following guides to manage Habitat packages on Chef Habitat On-Prem Builder: + +- [Bootstrap core Habitat packages](bootstrap_core_packages) +- [Update packages on Habitat Builder](update_packages) diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/packages/bootstrap_core_packages.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/packages/bootstrap_core_packages.md new file mode 100644 index 0000000000..06595cbe76 --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/packages/bootstrap_core_packages.md @@ -0,0 +1,97 @@ ++++ +title = "Bootstrap core Habitat packages" + +[menu] + [menu.habitat] + title = "Bootstrap core packages" + identifier = "habitat/on-prem-builder/packages/Bootstrap Core Packages" + parent = "habitat/on-prem-builder/packages" + weight = 20 ++++ + +When you first deploy Chef Habitat On-Prem Builder, it doesn't include any pre-installed packages. +This page explains how to bootstrap Builder with packages from [Chef's public Habitat Builder](https://bldr.habitat.sh). + +## Generate a personal access token + +You need a personal access token in your Habitat On-Prem Builder deployment to bootstrap the `core` packages and authenticate with the `hab` client. + +If you don't already have a token, generate one: + +1. In the top right corner of your Habitat On-Prem Builder site, select your Gravatar icon, then select **Profile**. +1. On the profile page, generate your access token and save it securely. + +## Add a license key + +In [Chef Habitat SaaS Builder](https://bldr.habitat.sh), you must have a Progress Chef license key in your [Builder profile](/habitat/builder_profile/) so you can access official Chef-maintained packages. + +## Enable native package support + +Some new LTS-supported packages include `native` packages. +To host LTS packages, you must configure your Habitat Builder deployment to allow native package support. +Enable the `nativepackages` feature and specify `core` as an allowed native package origin. +Edit your On-Prem Builder's `/hab/user/builder-api/config/user.toml` file so the `[api]` section looks like this: + +```toml +[api] +features_enabled = "nativepackages" +targets = ["x86_64-linux", "x86_64-linux-kernel2", "x86_64-windows"] +allowed_native_package_origins = ["core"] +``` + +## Bootstrap Builder in an online environment + +Chef Habitat On-Prem Builder doesn't include any pre-installed package sets. +You need to upload packages to populate Habitat Builder deployment. +To help bootstrap your On-Prem Builder with core packages, you can install the `habitat/pkg-sync` package. +This package downloads packages from the public [SaaS Builder](https://bldr.habitat.sh) and then uploads them in bulk to your Habitat Builder deployment. + +To bootstrap Habitat On-Prem Builder with a full set of stable core packages, run: + +```bash +sudo hab pkg install habitat/pkg-sync --channel LTS-2024 + +hab pkg exec habitat/pkg-sync pkg-sync \ + --bldr-url \ + --origin core \ + --channel stable \ + --private-builder-token \ + --public-builder-token +``` + +### Bootstrap Builder in an airgapped environment + +You can't transfer packages directly to Habitat Builder in an airgapped environment using `pkg-sync`, +so instead you have to download packages from the [public Habitat Builder](https://bldr.habitat.sh) and upload them to your airgapped deployment. + +Before you begin, you will need your personal access token that you use to communicate with your Habitat On-Prem Builder deployment and the URL of your Habitat On-Prem Builder deployment. + +To bootstrap an airgapped On-Prem Builder with stable core packages, follow these steps: + +1. Download the `habitat/pkg-sync` package on a machine with internet access: + + ```bash + sudo hab pkg install habitat/pkg-sync --channel LTS-2024 + ``` + +1. Generate a list of packages to download: + + ```shell + hab pkg exec habitat/pkg-sync pkg-sync --generate-airgap-list --origin core --channel stable + ``` + +1. Download packages into the `builder_bootstrap` directory on your computer: + + ```shell + hab pkg download --target x86_64-linux --channel stable --file package_list_x86_64-linux.txt --download-directory builder_bootstrap + hab pkg download --target x86_64-windows --channel stable --file package_list_x86_64-windows.txt --download-directory builder_bootstrap + ``` + +1. Archive the `builder_bootstrap` directory, then copy and extract the archive on a computer running in the airgapped environment. + +1. Bulk upload packages to Habitat Builder: + + ```bash + export HAB_AUTH_TOKEN= + hab pkg bulkupload --url https:// --channel stable --auto-create-origins builder_bootstrap/ + ``` diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/packages/update_packages.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/packages/update_packages.md new file mode 100644 index 0000000000..5ac82e3b6f --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/packages/update_packages.md @@ -0,0 +1,116 @@ ++++ +title = "Update packages on Habitat Builder" + +[menu] + [menu.habitat] + title = "Update packages" + identifier = "habitat/on-prem-builder/packages/update" + parent = "habitat/on-prem-builder/packages" + weight = 30 ++++ + +After a Chef Habitat release, you may want to update Habitat packages on Habitat Builder to the latest versions. +This document lays out the steps to take in order to perform such an update. + +## Enable native package support + +Chef Habitat and other Chef products are moving to long-term support (LTS) channels. +Some of the new LTS-supported packages include native packages. +To host LTS packages, you need to configure Habitat On-Prem Builder to allow native package support. + +To enable native package support, follow this step: + +- Edit the `/hab/user/builder-api/config/user.toml` file on your Habitat Builder deployment so that the `[api]` section looks like this: + + ```toml + [api] + features_enabled = "nativepackages" + targets = ["x86_64-linux", "x86_64-linux-kernel2", "x86_64-windows"] + allowed_native_package_origins = ["core"] + ``` + + This enables the `nativepackages` feature and specifies `core` as an allowed native package origin. + +## Bootstrap Builder with Habitat packages + +Use the `habitat/pkg-sync`package to install and sync packages with an Habitat On-Prem Builder deployment. +This package downloads packages from the public [SaaS Habitat Builder](https://bldr.habitat.sh) and performs a bulk upload to your Habitat Builder deployment. + +### Bootstrap Builder in an internet-connected environment + +To refresh your On-Prem Builder with the latest released Habitat packages, run the following commands. + +Before you begin, you will need your [personal access token](https://bldr.habitat.sh/#/profile) that you use to communicate with the public Habitat Builder and the URL of your Habitat On-Prem Builder deployment. + +1. Install the `habitat/pkg-sync` package. + + ```bash + sudo hab pkg install habitat/pkg-sync --channel LTS-2024 + ``` + +1. Sync packages from the public Habitat Builder to your Habitat On-Prem Builder deployment: + + ```bash + hab pkg exec habitat/pkg-sync pkg-sync \ + --bldr-url \ + --channel stable \ + --package-list habitat \ + --private-builder-token \ + --public-builder-token + ``` + + Replace: + + - `` with the URL of your Habitat Builder deployment. + - `` with your public Habitat Builder personal access token. + +### Bootstrap Builder in an airgapped environment + +For airgapped Habitat Builder deployments, `pkg-sync` can't transfer packages from the public internet to your instance. In this case, you'll download packages on an internet-connected computer, transfer them to your airgapped Habitat Builder, and bulk upload them. + +Follow these steps to refresh an airgapped On-Prem Builder with the latest stable Habitat packages: + +1. On an internet connected machine, install the `habitat/pkg-sync` package: + + ```sh + sudo hab pkg install habitat/pkg-sync --channel LTS-2024 + ``` + +1. Use `pkg-sync` to generate a list of packages and download packages from the public Habitat Builder: + + ```bash + hab pkg exec habitat/pkg-sync pkg-sync \ + --generate-airgap-list \ + --channel stable \ + --package-list habitat \ + --public-builder-token + + hab pkg download \ + -u https://bldr.habitat.sh \ + -z \ + --target x86_64-linux \ + --channel stable \ + --file package_list_x86_64-linux.txt \ + --download-directory habitat_packages + + hab pkg download \ + -u https://bldr.habitat.sh \ + -z \ + --target x86_64-windows \ + --channel stable \ + --file package_list_x86_64-windows.txt \ + --download-directory habitat_packages + ``` + +1. Create an archive of the `habitat_packages` directory, copy it to a computer in the airgapped environment, and extract the archive. + +1. Bulk upload the packages to your Habitat Builder deployment: + + ```bash + export HAB_AUTH_TOKEN= + hab pkg bulkupload \ + --url \ + --channel stable \ + --auto-create-origins \ + habitat_packages/ + ``` diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/troubleshooting.md b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/troubleshooting.md new file mode 100644 index 0000000000..67e9a835e7 --- /dev/null +++ b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/troubleshooting.md @@ -0,0 +1,242 @@ ++++ +title = "Troubleshooting Chef Habitat On-Prem Builder" + +[menu] + [menu.habitat] + title = "Troubleshooting" + identifier = "habitat/on-prem-builder/troubleshooting" + parent = "habitat/on-prem-builder" + weight = 500 ++++ + +This section covers several common problems that you might encounter and how to solve them. + +## Finding origin keys + +On Linux or macOS: + +```sh +ls -la /hab/cache/keys +ls -la $HOME/.hab/cache.keys +``` + +On Windows: + +```powershell +ls C:\hab\cache\keys +``` + +## Network access and proxy settings + +If the initial install fails, check that you have outgoing connectivity, and that you can successfully ping the following: + +- `raw.githubusercontent.com` +- `bldr.habitat.sh` + +If you have outgoing access with a proxy, ensure that HTTPS_PROXY is set correctly in your environment. + +Your Habitat On-Prem Builder deployment also needs the following inbound port open: + +- port 80 + +If you configured your proxy for the local session while installing Habitat Builder but are still receiving connection refusal errors like the one below, you may want to configure your proxy with the `/etc/environment` file or similar. + +```shell +-- Logs begin at Mon 2019-06-10 09:02:13 PDT. -- +Jun 10 09:35:15 hab[13161]: ∵ Missing package for core/hab-launcher +Jun 10 09:35:15 hab[13161]: » Installing core/hab-launcher +Jun 10 09:35:15 hab[13161]: ☁ Determining latest version of core/hab-launcher in the 'stable' channel +Jun 10 09:35:15 hab[13161]: ✗✗✗ +Jun 10 09:35:15 hab[13161]: ✗✗✗ Connection refused (os error 111) +Jun 10 09:35:15 hab[13161]: ✗✗✗ +Jun 10 09:35:15 systemd[1]: hab-sup.service: Main process exited, code=exited, status=1/FAILURE +Jun 10 09:35:15 hab[13171]: Supervisor not started. +Jun 10 09:35:15 systemd[1]: hab-sup.service: Unit entered failed state. +Jun 10 09:35:15 systemd[1]: hab-sup.service: Failed with result 'exit-code' +``` + +Please work with your enterprise network admin to ensure the appropriate firewall rules are configured for network access. + +### Authentication failure when logging in + +If you aren't able to log in, double check the settings that you configured your OAuth application with, as well as the URLs that you specified in your `bldr.env` file. + +### Unable to retrieve OAuth token + +If you were able to sign in to the authentication provider, but unable to authenticate with Chef Habitat's OAuth token, follow these steps: + +1. Open the `bldr.env` and verify the following settings: + + - The `APP_URL` value ends with a forward slash (`/`). + - The `OAUTH_REDIRECT_URL` value ends with a forward slash (`/`). + - The `OAUTH_CLIENT_ID` setting is complete and correct. + - The `OAUTH_CLIENT_SECRET` setting is complete and correct. + +1. Apply changes to the `bldr.env` by running the install script: + + ```bash + bash ./install.sh + ``` + +1. Restart the Chef Habitat services: + + ```bash + sudo systemctl restart hab-sup + ``` + +### Self-signed certificate files are missing + +If self-signed certificates are missing, verify the following: + +- If your self-signed certificates are missing, copy them into the `/hab/cache/ssl` directory. The latest version of Chef Habitat On-Prem Builder expects certificates in that directory. + +- Name your certificate files using the pattern `appname-cert.cert` or `appname-cert.pem`. For example, `automate-cert.cert` or `automate-cert.pem`. + +- Don't use `cert.pem`, which is reserved for the Chef Habitat system. + If you overwrite this file, Chef Habitat On-Prem Builder will fail. + +After correcting those issues, restart the Chef Habitat services: + +```bash +sudo systemctl restart hab-sup +``` + +### Connection refused (os error 111) + +If you configured your proxy for the local session during installation but still see connection refused errors, try setting your proxy in the `/etc/environment` file or a similar system-wide location. +Work with your enterprise network admin to make sure the correct firewall rules are in place for network access. + +```shell +-- Logs begin at Mon 2019-06-10 09:02:13 PDT. -- +Jun 10 09:35:15 hab[13161]: ∵ Missing package for core/hab-launcher +Jun 10 09:35:15 hab[13161]: » Installing core/hab-launcher +Jun 10 09:35:15 hab[13161]: ☁ Determining latest version of corehab-launcher in the 'stable' channel +Jun 10 09:35:15 hab[13161]: ✗✗✗ +Jun 10 09:35:15 hab[13161]: ✗✗✗ Connection refused (os error 111) +Jun 10 09:35:15 hab[13161]: ✗✗✗ +Jun 10 09:35:15 systemd[1]: hab-sup.service: Main process exited,code=exited, status=1/FAILURE +Jun 10 09:35:15 hab[13171]: Supervisor not started. +Jun 10 09:35:15 systemd[1]: hab-sup.service: Unit entered failed state. +Jun 10 09:35:15 systemd[1]: hab-sup.service: Failed with result 'exit-code' +``` + +### Error "sorry, too many clients already" + +If the Habitat services don't start as expected, use `journalctl -fu hab-sup` to check the service logs (see below for enabling debug logging). + +If you see a PostgreSQL error saying "sorry, too many clients already," you may need to increase the number of allowed connections to the database. + +To increase the connection limit, run: + +```bash +echo 'max_connections=200' | hab config apply builder-datastore.default $(date +%s) +``` + +Wait for the datastore service to restart. +If it doesn't restart automatically, run: + +```bash +sudo systemctl restart hab-sup +``` + +### Error "Too many open files" + +If you see this error in the supervisor logs, you may need to increase the file ulimit on your system. +Chef Habitat On-Prem Builder includes an expanded file limit in its systemd configuration, but some distributions (for example, CentOS 7) may require additional configuration. + +Add the following lines to the end of your `/etc/security/limits.conf` file, then restart your system: + +```text +* soft nofile 65535 +* hard nofile 65535 +``` + +### Error "Text file busy" + +If you see a "Text file too busy" error during install, try running the install step again. + +### Error when bootstrapping core packages + +You may see the following error when bootstrapping core packages. +If this happens, the bootstrap process will keep retrying, and the upload will eventually succeed. +Let the process continue until it completes. + +```shell +✗✗✗ +✗✗✗ Pooled stream disconnected +✗✗✗ +``` + +If some packages don't upload, try re-uploading them manually with the `hab pkg upload` command. + +This error may also indicate that your installation doesn't have enough CPU, RAM, or other resources. +Consider allocating more resources (for example, if running on a VM) or moving to a larger instance. + +### Error uploading large packages + +By default, Chef Habitat On-Prem Builder has a 2 GB package limit. +If you need to increase this limit, update the Chef Habitat On-Prem Builder configuration. + +To change the upload limit, follow these steps: + +1. Create a file named `config.toml` with the following content: + + ```toml + [nginx] + max_body_size = "" + proxy_send_timeout = 360 + proxy_read_timeout = 360 + + [http] + keepalive_timeout = "360s" + ``` + + Replace `` with your desired size limit, for example, `3072m` for 3 GB. + +1. Apply the new configuration: + + ```bash + hab config apply builder-api-proxy.default $(date +%s) config.toml + ``` + +After you apply the configuration, try the upload again. + +If you still have issues, you may need to adjust the timeout for the Chef Habitat client. +Set the `HAB_CLIENT_SOCKET_TIMEOUT` environment variable to the desired timeout in seconds. +For example: + +```bash +HAB_CLIENT_SOCKET_TIMEOUT=360 hab pkg upload -u -z +``` + +### Package shows up in the Builder UI and `hab pkg search`, but `hab pkg install` fails + +If you run into a situation where you have a package populated in the Chef Habitat On-Prem Builder, but it is failing to install with a `Not Found` status, it is possible that there was a prior problem with populating the MinIO backend with the package artifact. + +If you have the package artifact on-disk (for example, in the `hab/cache/artifacts` directory), you can try to upload the missing package again with the following command (update the parameters as appropriate): + +```bash +hab pkg upload -u -z --force +``` + +### on-prem-archive.sh fails during `populate-depot` with `403` error when uploading core packages + +When you populate your Chef Habitat On-Prem Builder with upstream core packages, you might see a repeated error for every package: + +```sh +Uploading hart files. + +[1/958] Uploading ./core-img-0.5.4-20190201011741-x86_64-linux.hart to the depot at https://bldr.example.com + 75 B / 75 B | [=========================================] 100.00 % 384 B/s +✗✗✗ +✗✗✗ [403 Forbidden] +✗✗✗ +``` + +Make sure you've created the `core` origin in your Habitat Builder deployment. +The upload fails if the `core` origin doesn't exist. +After you create the `core` origin, try the upload again. + +## Support + +You can post questions or issues on the [Habitat Forum](https://discourse.chef.io/), on our [Slack channel](https://community.chef.io/slack), or file issues directly at the [Github repo](https://github.com/habitat-sh/on-prem-builder/issues). diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/static/images/habitat/on_prem_builder/builder_architecture.png b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/static/images/habitat/on_prem_builder/builder_architecture.png new file mode 100644 index 0000000000..1cfd85561b Binary files /dev/null and b/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/static/images/habitat/on_prem_builder/builder_architecture.png differ diff --git a/_vendor/modules.txt b/_vendor/modules.txt index bb17b76105..1a661365b3 100644 --- a/_vendor/modules.txt +++ b/_vendor/modules.txt @@ -1,6 +1,7 @@ # github.com/chef/automate/components/docs-chef-io v0.0.0-20250617123043-e9e3b2463824 # github.com/chef/desktop-config/docs-chef-io v0.0.0-20240814044820-5af667d41a43 -# github.com/habitat-sh/habitat/components/docs-chef-io v0.0.0-20250523161510-a254ccc738ad +# github.com/habitat-sh/habitat/components/docs-chef-io v0.0.0-20250703193412-93daafc684a8 +# github.com/habitat-sh/on-prem-builder/docs-chef-io v0.0.0-20250703193242-204bceb9833e # github.com/chef/chef-server/docs-chef-io v0.0.0-20250414141619-a0fb7ff68e94 # github.com/inspec/inspec/docs-chef-io v0.0.0-20250123110211-42364d842e34 # github.com/inspec/inspec-alicloud/docs-chef-io v0.0.0-20240122032124-a1d2a214e170 diff --git a/config/_default/menu.toml b/config/_default/menu.toml index c124bf1617..15960f0ce8 100644 --- a/config/_default/menu.toml +++ b/config/_default/menu.toml @@ -369,6 +369,118 @@ identifier = "desktop" # End Chef Desktop Menu #### +#### +# Chef Habitat Menu +#### + +[[habitat]] +title = "Chef Habitat" +identifier = "habitat" + + [[habitat]] + title = "Install Habitat" + identifier = "habitat/install" + parent = "habitat" + weight = 15 + + [[habitat]] + title = "SaaS Builder" + identifier = "habitat/builder" + parent = "habitat" + weight = 20 + + [[habitat]] + title = "On-Prem Builder" + identifier = "habitat/on-prem-builder" + parent = "habitat" + weight = 30 + + [[habitat]] + title = "Install" + identifier = "habitat/on-prem-builder/install" + parent = "habitat/on-prem-builder" + weight = 20 + + [[habitat]] + title = "Configure" + identifier = "habitat/on-prem-builder/configure" + parent = "habitat/on-prem-builder" + weight = 30 + + [[habitat]] + title = "Manage" + identifier = "habitat/on-prem-builder/manage" + parent = "habitat/on-prem-builder" + weight = 40 + + [[habitat]] + title = "Origins" + identifier = "habitat/on-prem-builder/origins" + parent = "habitat/on-prem-builder" + weight = 50 + + [[habitat]] + title = "Packages" + identifier = "habitat/on-prem-builder/packages" + parent = "habitat/on-prem-builder" + weight = 60 + + [[habitat]] + title = "Origins" + identifier = "habitat/origins" + parent = "habitat" + weight = 40 + + [[habitat]] + title = "Packages" + identifier = "habitat/packages" + parent = "habitat" + weight = 50 + + [[habitat]] + title = "Plans" + identifier = "habitat/plans" + parent = "habitat" + weight = 60 + + [[habitat]] + title = "Services" + identifier = "habitat/services" + parent = "habitat" + weight = 70 + + [[habitat]] + title = "Supervisors" + identifier = "habitat/supervisors" + parent = "habitat" + weight = 80 + + [[habitat]] + title = "Reference" + identifier = "habitat/reference" + parent = "habitat" + weight = 90 + + [[habitat]] + title = "API" + identifier = "habitat/reference/api" + parent = "habitat/reference" + + [[habitat]] + title = "Containers" + identifier = "habitat/containers" + parent = "habitat" + weight = 200 + + [[habitat]] + title = "Diagrams" + identifier = "habitat/diagrams" + parent = "habitat" + weight = 500 + +#### +# End Chef Habitat Menu +#### #### # Chef Infra Server Menu diff --git a/config/_default/module.toml b/config/_default/module.toml index e20dc9799c..6fa4d6da47 100644 --- a/config/_default/module.toml +++ b/config/_default/module.toml @@ -79,6 +79,23 @@ workspace = '' source = "layouts" target = "layouts" +### +# Chef Habitat on-prem Builder +### + +[[imports]] + disable = false + ignoreConfig = false + path = "github.com/habitat-sh/on-prem-builder/docs-chef-io" + +[[imports.mounts]] + source = "content" + target = "content" + +[[imports.mounts]] + source = "static" + target = "static" + ### # Chef Infra Server ### diff --git a/go.mod b/go.mod index 6658a9c42b..581cd76cda 100644 --- a/go.mod +++ b/go.mod @@ -1,6 +1,6 @@ module github.com/chef/chef-web-docs -go 1.22 +go 1.24.2 require ( github.com/chef/automate/components/docs-chef-io v0.0.0-20250617123043-e9e3b2463824 // indirect @@ -15,7 +15,8 @@ require ( github.com/chef/samples v0.0.0-20250424163637-3393187e624c // indirect github.com/chef/supermarket/docs-chef-io v0.0.0-20250602140848-cded623a3f5c // indirect github.com/cowboy/jquery-hashchange v0.0.0-20100902193700-0310f3847f90 // indirect - github.com/habitat-sh/habitat/components/docs-chef-io v0.0.0-20250523161510-a254ccc738ad // indirect + github.com/habitat-sh/habitat/components/docs-chef-io v0.0.0-20250703193412-93daafc684a8 // indirect + github.com/habitat-sh/on-prem-builder/docs-chef-io v0.0.0-20250703193242-204bceb9833e // indirect github.com/inspec/inspec-alicloud/docs-chef-io v0.0.0-20240122032124-a1d2a214e170 // indirect github.com/inspec/inspec-aws/docs-chef-io v0.0.0-20240122032232-049dcf822eef // indirect github.com/inspec/inspec-azure/docs-chef-io v0.0.0-20240122032234-c1394fc25525 // indirect diff --git a/go.sum b/go.sum index 8af7b88d7e..e0a7351bea 100644 --- a/go.sum +++ b/go.sum @@ -22,8 +22,10 @@ github.com/chef/supermarket/docs-chef-io v0.0.0-20250602140848-cded623a3f5c h1:q github.com/chef/supermarket/docs-chef-io v0.0.0-20250602140848-cded623a3f5c/go.mod h1:D+9mmEZxCwpdhZ8LrEODBWMwMufmJUubSt5NlU/lLB4= github.com/cowboy/jquery-hashchange v0.0.0-20100902193700-0310f3847f90 h1:p/a5iSATj0OjrqJLX/YKxYdGXhZzW58yyyNIC4JY4S0= github.com/cowboy/jquery-hashchange v0.0.0-20100902193700-0310f3847f90/go.mod h1:N/6F0+wmdvL6k0AjqyKIncMRClKAN92atjZdTLtYMaw= -github.com/habitat-sh/habitat/components/docs-chef-io v0.0.0-20250523161510-a254ccc738ad h1:ouEmy8zUhSus+Tqi0IDVktKo6OCCGQ84xmGNsDQfKdw= -github.com/habitat-sh/habitat/components/docs-chef-io v0.0.0-20250523161510-a254ccc738ad/go.mod h1:5GKz/BtTWeTr8vdVQPkvGDQkQ+xiGWLkDsPOXhu2Ps4= +github.com/habitat-sh/habitat/components/docs-chef-io v0.0.0-20250703193412-93daafc684a8 h1:euxH1nuHIWgo6hr6Z/CkHOGik+JIghtkrFXUj01hB+4= +github.com/habitat-sh/habitat/components/docs-chef-io v0.0.0-20250703193412-93daafc684a8/go.mod h1:5GKz/BtTWeTr8vdVQPkvGDQkQ+xiGWLkDsPOXhu2Ps4= +github.com/habitat-sh/on-prem-builder/docs-chef-io v0.0.0-20250703193242-204bceb9833e h1:Rqg0DsHGRpQNUuH8ewyZR5cGf8g1xIr2f+zRqe04JDY= +github.com/habitat-sh/on-prem-builder/docs-chef-io v0.0.0-20250703193242-204bceb9833e/go.mod h1:qrPLVomtsigVjzB+Q0hhZJx/0RVzs8GQPOzovYflc5k= github.com/inspec/inspec-alicloud/docs-chef-io v0.0.0-20240122032124-a1d2a214e170 h1:Q9jEEyv8nZAN5NgJXwMoqjngSz6Bc5ruNc9V72Hk4b4= github.com/inspec/inspec-alicloud/docs-chef-io v0.0.0-20240122032124-a1d2a214e170/go.mod h1:tAazDDBtR5yCl/FNWHnrmkxpfxnOo9B99DyfRE7JH1c= github.com/inspec/inspec-aws/docs-chef-io v0.0.0-20240122032232-049dcf822eef h1:r+GoVO6zbIAtusZ2w6MwUhtDAJicQkYbX0iWwZmuXfQ=