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 deleted file mode 100644 index 9246494343..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/config.toml +++ /dev/null @@ -1,2 +0,0 @@ -[params.habitat] -gh_path = "https://github.com/habitat-sh/habitat/tree/main/components/docs-chef-io/content/" diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/_index.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/_index.md deleted file mode 100644 index 86753c6257..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/_index.md +++ /dev/null @@ -1,108 +0,0 @@ -+++ -title = "Chef Habitat Overview" -aliases = ["/habitat/reference/", "/habitat/glossary/", "/habitat/diagrams/"] -gh_repo = "habitat" - -[cascade] - product = ["habitat"] - -[menu] - [menu.habitat] - title = "Overview" - identifier = "habitat/Overview" - parent = "habitat" - weight = 1 -+++ - -Chef Habitat is a workload-packaging, orchestration, and deployment system that allows you to build, package, deploy, and manage applications and services without worrying about which infrastructure your application will deploy on, and without any rewriting or refactoring if you switch to a different infrastructure. - -Habitat separates the platform-independent parts of your application—the build dependencies, runtime dependencies, lifecycle events, and application codebase—from the operating system or deployment environment that the application will run on, and bundles it into an immutable Habitat Package. -The package is sent to the Chef Habitat Builder (SaaS or on-prem), which acts as a package store like Docker Hub where you can store, build, and deploy your Habitat package. -Habitat Supervisor pulls packages from Habitat Builder, and will start, stop, run, monitor, and update your application based on the plan and lifecycle hooks you define in the package. -Habitat Supervisor runs on bare metal, virtual machines, containers, or Platform-as-a-Service environments. -A package under management by a Supervisor is called a service. -Services can be joined together in a service group, which is a collection of services with the same package and topology type that are connected together across a Supervisor network. - -## Components - -### Habitat Builder - -{{< readfile file="content/habitat/reusable/md/habitat_builder_overview.md" >}} - -For more information, see the [Chef Habitat Builder]({{< relref "/habitat/builder_overview" >}}) documentation. - -### Habitat Package - -A Habitat Package is an artifact that contains the application codebase, lifecycle hooks, and a manifest that defines build and runtime dependencies of the application. -The package is bundled into a Habitat Artifact (.HART) file, which is a binary distribution of a given package built with Chef Habitat. -The package is immutable and cryptographically signed with a key so you can verify that the artifact came from the place you expected it to come from. -Artifacts can be exported to run in a variety of runtimes with zero refactoring or rewriting. - -### Plan - -{{< readfile file="content/habitat/reusable/md/habitat_plans_overview.md" >}} - -For more information, see the [plan]({{< relref "plan_writing" >}}) documentation. - -### Services - -{{< readfile file="content/habitat/reusable/md/habitat_services_overview.md" >}} - -See the [services documentation]({{< relref "about_services" >}}) for more information. - -### Habitat Studio - -{{< readfile file="content/habitat/reusable/md/habitat_studio_overview.md" >}} - -See the [Habitat Studio documentation]({{< relref "studio" >}}) for more information. - -### Habitat Supervisor - -{{< readfile file="content/habitat/reusable/md/habitat_supervisor_overview.md" >}} - -See the [Habitat Supervisor documentation]({{< relref "sup" >}}) for more information. - -## When Should I Use Chef Habitat? - -Chef Habitat allows you to build and package your applications and deploy them anywhere without having to refactor or rewrite your package for each platform. -Everything that the application needs to run is defined, without assuming anything about the underlying infrastructure that the application is running on. - -This will allow you to repackage and modernize legacy workloads in-place to increase their manageability, make them portable, and migrate them to modern operating systems or even cloud-native infrastructure like containers. - -You can also develop your application if you are unsure of the infrastructure your application will run on, or in the event that business requirements change and you have to switch your application to a different environment. - -## Next Steps - -- [Download and install the Chef Habitat CLI]({{< relref "/habitat/install_habitat" >}}). -- [Create an account]({{< relref "/habitat/builder_account" >}}) on the [Habitat Builder SaaS](https://bldr.habitat.sh). -- Try our [getting started guide](get_started) for Chef Habitat. - -## Additional Resources - -### Download - -- [Download Chef Habitat](https://www.chef.io/downloads) -- [Install documentation]({{< relref "/habitat/install_habitat" >}}) - -### Learning - -- [Learn Chef: Deliver Applications with Chef Habitat](https://learn.chef.io/courses/course-v1:chef+Habitat101+Perpetual/about) -- [Chef Habitat webinars](https://www.chef.io/webinars?products=chef-habitat&page=1) -- [Resource Library](https://www.chef.io/resources?products=chef-habitat&page=1) - -### Community - -- [Chef Habitat on Discourse](https://discourse.chef.io/c/habitat/12) -- [Chef Habitat in the Chef Blog](https://www.chef.io/blog/category/chef-habitat) -- [Chef Habitat Community Resources](https://community.chef.io/tools/chef-habitat) - -### Support - -- [Chef Support](https://www.chef.io/support) - -### GitHub Repositories - -- [Chef Habitat repository](https://github.com/habitat-sh/habitat) -- [Chef Habitat Core Plans repository](https://github.com/habitat-sh/core-plans) -- [Chef Habitat Builder repository](https://github.com/habitat-sh/builder) -- [Chef Habitat Builder on-prem repository](https://github.com/habitat-sh/on-prem-builder) diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/about_services.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/about_services.md deleted file mode 100644 index 0ae9b8b9b8..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/about_services.md +++ /dev/null @@ -1,48 +0,0 @@ -+++ -title = "About Services" -aliases = ["/habitat/using-habitat/"] -date = 2020-10-26T18:37:38-07:00 -draft = false -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "About Services" - identifier = "habitat/services/About Services" - parent = "habitat/services" - weight = 10 -+++ - -A service is a Chef Habitat package running under a Chef Habitat Supervisor. - -## Service Group - -A service group is a set of one or more running services with a shared configuration -and topology. If a service is started without explicitly naming the -group, it is assigned to the default group for the name of that package. For example: - -- `redis.default` -- `postgres.financialdb` (possibly running in a cluster) -- `postgres.userdb` (possibly running in a cluster) - -## Topology - -Chef Habitat allows you to define the topology of your service groups, which bakes -in certain behaviors. - -### Standalone - -This is the default topology, useful for services inside a group that are completely -independent from one another. Note that this still means they can share the same -configuration. - -### Leader / Follower - -This topology allows a distributed application running on at least three Chef Habitat -nodes to use a leader/follower configuration. Leaders are elected with Chef Habitat's -leader election algorithm, and followers are restarted to reflect a configuration -that follows the new leader. Subsequent elections due to leader failure will update -both leader and follower configuration data. - -You can read more about the internals behind the elections in our [advanced developer -documentation]({{< relref "sup_crypto#leader-election" >}}). \ No newline at end of file diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/aks.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/aks.md deleted file mode 100644 index 11923c925b..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/aks.md +++ /dev/null @@ -1,72 +0,0 @@ -+++ -title = "Azure Container Services (AKS)" -description = "Azure and Kubernetes K8" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Azure Container Services (AKS)" - identifier = "habitat/containers/aks Chef Habitat Azure Kubernetes" - parent = "habitat/containers" - weight = 40 -+++ - -[Azure Container Services (AKS)](https://azure.microsoft.com/services/container-service/) -is a fully managed Kubernetes service running on the Azure platform. - -## Azure Container Registry (ACR) - -Azure Container Registry is a managed Docker container registry service used for storing private Docker container images. It's a fully managed Azure resource and gives you local, network-close storage of your container images when deploying to AKS. Chef Habitat Builder has native integration with this service so you can publish your packages directly to Azure Container Registry. - -In order to do this you need to create an Azure Service Principal that has `Owner` rights -on your ACR instance. You can do this with the following script, changing the environment -variable values to match your environment. - -``` - !/bin/bash - - R_RESOURCE_GROUP=myACRResourceGroup - R_NAME=myACRRegistry -BLDR_PRINCIPAL_NAME=myPrincipalName -BLDR_PRINCIPAL_PASSWORD="ThisIsVeryStrongPassword" - - Create Service Principal for Chef Habitat Builder - R_ID=$(az acr show --name $ACR_NAME --resource-group $ACR_RESOURCE_GROUP --query "id" --output tsv) - ad sp create-for-rbac --scopes $ACR_ID --role Owner --password "$BLDR_PRINCIPAL_PASSWORD" --name $BLDR_PRINCIPAL_NAME -BLDR_ID=$(az ad sp list --display-name $BLDR_PRINCIPAL_NAME --query "[].appId" --output tsv) - - ho "Configuration details for Habitat Builder Principal:" -echo " ID : $BLDR_ID" -echo " Password : $BLDR_PRINCIPAL_PASSWORD" -``` - -Note: The unique Service Principal Name (the UUID) should be provided in the Chef Habitat Builder -configuration. - -## Connecting ACR and AKS - -Since ACR is a private Docker registry, AKS must be authorized to pull images from it. The best way is to create a role assignment on the Service Principal that is automatically created for AKS, granting it `Reader` access on your ACR instance. - -To do this you can use the following script, changing the environment variable values to match your configuration. - -``` -#!/bin/bash - -AKS_RESOURCE_GROUP=myAKSResourceGroup -AKS_CLUSTER_NAME=myAKSCluster -ACR_RESOURCE_GROUP=myACRResourceGroup -ACR_NAME=myACRRegistry - -# Get the id of the service principal configured for AKS -CLIENT_ID=$(az aks show --resource-group $AKS_RESOURCE_GROUP --name $AKS_CLUSTER_NAME --query "servicePrincipalProfile.clientId" --output tsv) - -# Get the ACR Registry Resource ID -ACR_ID=$(az acr show --name $ACR_NAME --resource-group $ACR_RESOURCE_GROUP --query "id" --output tsv) - -# Create Role Assignment -az role assignment create --assignee $CLIENT_ID --role Reader --scope $ACR_ID -``` - -## Related Reading - -* [Authenticate with Azure Container Registry from Azure Container Service](https://docs.microsoft.com/azure/container-registry/container-registry-auth-aks#grant-aks-access-to-acr) diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/application_lifecycle_hooks.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/application_lifecycle_hooks.md deleted file mode 100644 index 7ce110b90a..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/application_lifecycle_hooks.md +++ /dev/null @@ -1,161 +0,0 @@ -+++ -title = "Application Lifecycle Hooks" -description = "Control service runtime actions with application lifecycle hooks" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Application Lifecycle Hooks" - identifier = "habitat/reference/application-lifecycle-hooks Plan Lifecycle Hooks" - parent = "habitat/reference" - -+++ - -Each plan can specify lifecycle event handlers, or hooks, to perform certain actions during a service's runtime. Each hook is a script with a [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) defined at the top to specify the interpreter to be used. On Windows, Powershell Core is the only interpreter ever used. - -To define a hook, simply create a file of the same name in `/my_plan_name/hooks/`, for example, `/postgresql/hooks/health-check`. - -Optionally you may add an extension to the hook file. For example, you might create `/postgresql/hooks/health-check.sh` which can be useful in some editors to automatically take advantage of syntax highlighting. Note that having two files for the same hook but with different extensions is not permitted. For example you might create a `run.sh` and `run.ps1` to support both Linux and Windows packages. If you would like to create different hooks for different platforms, you must use [target directories]({{< relref "plan_writing#writing-a-plan-for-multiple-platform-targets" >}}). - -{{< warning >}} -You cannot block the thread in a hook unless it is in the `run` hook. Never call `hab` or `sleep` in a hook that is not the `run` hook. -{{< /warning >}} - -## Runtime Settings - -[Chef Habitat's runtime configuration settings]({{< relref "service_templates" >}}) can be used in any of the plan hooks and also in any templatized configuration file for your application or service. - -{{< note >}} -In Chef Habitat 0.68.0 and less, some hooks used `_` in their names. This is now deprecated; if you used them, please use `-` instead. -{{< /note >}} - -### file-updated - -File location: `/hooks/file-updated`. This hook is run whenever a configuration file that is not related to a user or about the state of the service instances is updated. - -### health-check - -**File location**: `/hooks/health-check`. **Default**: 30 seconds - -This hook repeats at a configured interval. There are two exceptions to the interval used between `health-check` runs: - -- If the `health-check` hook exits with a non-`ok` status the next `health-check` will run after the default `health-check` interval (thirty seconds). This is only done when the configured interval is greater than the default interval. -- If the `health-check` hook returns an `ok` status for the first time, then the next `health-check` will run after a randomly chosen delay between 0 and the configured `health-check` interval. This introduces a splay - a degree of difference - in the timing between the first and second `health-check` runs. All following health-check hooks run at the configured interval. The splay prevents more than one health-check hook from starting at the same time by giving each of them a unique starting point. - -The `health-check` script must return a valid exit code from the list below. - -- **0**- ok -- **1**- warning -- **2**- critical -- **3**- unknown -- any other code - failed health check with additional output taken from `health-check` stdout. - -A `health-check` hook can use the following as a template: - -```bash hooks/health-check -#!/bin/sh - -# define default return code as 0 -rc=0 -program_that_returns_a_status -case $? in - 0) - rc=1 ;; - 3) - rc=0 ;; - 4) - rc=2 ;; - *) - rc=3 ;; -esac - -exit $rc -``` - -### init - -File location: `/hooks/init`. This hook is run when a Chef Habitat topology starts. - -{{< note >}} -If the init hook fails with a non-zero exit code, the service will be restarted with the [configured service backoff]({{< relref "service_restarts" >}}). -{{< /note >}} - -### install - -File location: `/hooks/install`. This hook is run when a package is initially installed. - -An `install` hook may be triggered by `hab pkg install` or by a Supervisor loading a new package. Note that any package can define an `install` hook and it is not limited to packages that are loaded as services into a Supervisor. A package may have dependencies defined in `pkg_deps` or `pkg_build_deps` that define their own `install` hook. An `install` hook defined in an dependant package that has not yet been installed will run when the parent package is installed. However `install` hooks in a runtime dependency (`pkg_deps`) will not run when loaded via a package `build` inside of a Studio. - -The exit code returned from an `install` hook will be "remembered". If a previously installed package is either installed again via `hab pkg install` or loaded into a Supervisor, its `install` hook will be rerun if it previously failed (exited with a non `0` result) or has not been previously run (perhaps because `--ignore-install-hook` was passed to `hab pkg install`). - -An `install` hook, unlike other hooks, will not have access to any census data exposed via binds or the `svc` namespace. Also, configuration in `svc_config_path` is not accessible to an `install` hook. If an `install` hook needs to use templated configuration files, templates located in the `svc_config_install_path` may be referenced. This location will contain rendered templates in a package's `config_install` folder. Finally, any configuration updates made during a service's runtime that would alter an `install` hook or any configuration template in `svc_config_install_path` will not cause a service to reload. - -### reload - -File location: `/hooks/reload`. This hook is now deprecated; you should use `reconfigure` instead (see below). To provide backward compatibility, if a `reload` hook is provided, the service will restart in response to configuration changes. - -### reconfigure - -File location: `/hooks/reconfigure`. A `reconfigure` hook can be written for services that can respond to changes in `/config` without requiring a restart. This hook will execute **instead** of the default behavior of restarting the process. `{{pkg.svc_pid_file}}` can be used to get the `PID` of the service. - -Habitat does not support changing the `PID` of the underlying service in any lifecycle hook. If part of a service's reconfiguration relies on changing the `PID`, you should not provide a `reconfigure` hook, and instead, use the default behavior of restarting the service for reconfiguration. - -The `reconfigure` hook is not necessarily run on every change to `/config`. The `reconfigure` hook will not be run if the service restarts before the `reconfigure` hook has run. The restart is considered sufficient for reconfiguring the service. For example, when applying a configuration that changes both the `run` hook and `/config`, the change to the `run` hook will trigger a restart. Therefore, the `reconfigure` hook will not be run. To put it another way, the `reconfigure` hook will only respond to changes in `/config` after the service has started. - -### suitability - -File location: `/hooks/suitability`. The suitability hook allows a service to report a priority by which it should be elected leader. The hook is called when a new election is triggered and the last line it outputs to `stdout` should be a number parsable as a `u64`. In the event that a leader goes down and an election is started the service with the highest reported suitability will become the new leader. - -### run - -File location: `/hooks/run`. This hook is run when one of the following conditions occur: - -- The main topology starts, after the `init` hook has been called. -- When a package is updated, after the `init` hook has been called. -- When the package config changes, after the `init` hook has been called, but before a `reconfigure` hook is called. - -You can use this hook in place of `$pkg_svc_run` when you need more complex behavior such as setting environment variables or command options that are based on dynamic configuration. - -Services run using this hook should do two things: - -- Redirect stderr to stdout (e.g. with `exec 2>&1` at the start of the hook) -- Call the command to execute with `exec ` rather than running the command directly. This ensures the command is executed in the same process and that the service will restart correctly on configuration changes. - -It is important to also consider what side effects the command to execute will have. For example, does the command spin off other processes in separate process groups? If so, they may not be cleaned up automatically when the system is reconfigured. In general, the command executed should behave in a manner similar to a daemon, and be able to clean up properly after itself when it receives a SIGTERM, and properly forward signals to other processes that it creates. For an even more specific example: let's say you are trying to start a node.js service. Instead of your command being `npm start`, you should use `node server.js` directly. - -A run hook can use the following as a template: - -```bash hooks/run -#!/bin/sh - -#redirect stderr -exec 2>&1 - -# Set some environment variables -export MY_ENVIRONMENT_VARIABLE=1 -export MY_OTHER_ENVIRONMENT_VARIABLE=2 - -# Run the command -exec my_command --option {{cfg.option}} --option2 {{cfg.option2}} -``` - -{{< note >}} -If the run hook exits it will be considered as a run failure. The service will be restarted with the [configured service backoff]({{< relref "service_restarts" >}}) regardless of the exit code that -was returned by the hook. -{{< /note >}} - -### post-run - -File location: `/hooks/post-run`. The post run hook will get executed after initial startup. For many data services creation of specific users / roles or datastores is required. This needs to happen once the service has already started. - -### post-stop - -File location: `/hooks/post-stop`. The post-stop hook will get executed after service has been stopped successfully. You may use this hook to undo what the `init` hook has done. - -### uninstall - -File location: `/hooks/uninstall`. This hook is run when a package is uninstalled. - -The `uninstall` hook runs when the last package of an `origin/package` is uninstalled. If there are other versions or revisions installed for the package, the `uninstall` hook is skipped. When more than one revision of an origin are uninstalled at the same time, the process removes them from oldest to newest. This ensures that the uninstall hook of the latest revision is the version that runs. - -Like the `install` hook, the `uninstall` hook is not limited to packages that are loaded as services into a Supervisor. Also like the `install` hook, configuration in `svc_config_path` is not accessible to an `uninstall` hook. If an `uninstall` hook needs to use templated configuration files, templates located in the `svc_config_install_path` may be referenced. This location will contain rendered templates in a package's `config_install` folder. Finally, any configuration updates made during a service's runtime that would alter an `uninstall` hook or any configuration template in `svc_config_install_path` will not cause a service to reload. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/application_rebuild_flow.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/application_rebuild_flow.md deleted file mode 100644 index 526a9b7350..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/application_rebuild_flow.md +++ /dev/null @@ -1,15 +0,0 @@ -+++ -title = "Application Rebuild Flow" -description = "Application Rebuild Flow" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Application Rebuild Flow" - identifier = "habitat/diagrams/application-rebuild-flow Application Rebuild Flow" - parent = "habitat/diagrams" - weight = 40 - -+++ -![Chef Habitat Application Rebuild Flow Diagram](/images/habitat/habitat-application-rebuild-flow.png) - diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/architecture_overview.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/architecture_overview.md deleted file mode 100644 index 9457ad8a09..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/architecture_overview.md +++ /dev/null @@ -1,15 +0,0 @@ -+++ -title = "Chef Habitat Architecture Overview" -description = "Chef Habitat Architecture Overview" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Architecture Overview" - identifier = "habitat/diagrams/architecture-overview" - parent = "habitat/diagrams" - weight = 10 - -+++ - -![Chef Habitat Architecture Overview Diagram](/images/habitat/habitat-architecture-overview.png) diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/binary_wrapper.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/binary_wrapper.md deleted file mode 100644 index 48dc7d3546..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/binary_wrapper.md +++ /dev/null @@ -1,90 +0,0 @@ -+++ -title = "Binary Wrapper Packages" -description = "Tips and tricks for managing hardcoded library dependencies in binaries" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Binary Wrapper Packages" - identifier = "habitat/plans/binary-wrapper" - parent = "habitat/plans" - -+++ - -While Chef Habitat provides the best behavior for applications that can be compiled from source into the Chef Habitat ecosystem, it can also bring the same management benefits to applications distributed in binary-only form. - -You can write plans to package up these binary artifacts with minimal special handling. This article covers some tips and tricks for getting this software into Chef Habitat. - -## Override The Build Phases You Don't Need - -A Chef Habitat package build proceeds in phases: download, verification, unpacking (where you would also patch source code, if you had it), build, and finally installation. Each of these phases has [default behavior]({{< relref "build_phase_callbacks" >}}) within the build system. - -When building binary packages, you override the behavior of phases that do not apply to you. At the very minimum, you must override the `do_build` and `do_install` phases, for example: - -```bash plan.sh -(...) -do_build() { - # relocate library dependencies here, if needed -- see next topic - return 0 -} - -do_install() { - mkdir -p $pkg_prefix/bin - cp $PLAN_CONTEXT/bin/hello_world $pkg_prefix/bin/hello_world - chmod +x $pkg_prefix/bin/hello_world -} -``` - -## Relocate Hard-Coded Library Dependencies If Possible - -On Linux, many binaries hardcode library dependencies to `/lib` or `/lib64` inside their ELF symbol table. Unfortunately, this means that Chef Habitat is unable to provide dependency isolation guarantees if packages are dependent on any operating system's libraries in those directories. These Chef Habitat packages will also fail to run in minimal environments like containers built using `hab-pkg-export-docker`, because there will not be a `glibc` inside `/lib` or `/lib64`. - -> Note: On Windows, library dependency locations are not maintained in a binary file's headers. See [this MSDN article](https://msdn.microsoft.com/library/windows/desktop/ms682586(v=vs.85).aspx) for a complete explanation of how Windows binaries are located. However, it's typically sufficient to ensure that the dependent binaries are on the `PATH`. You should make sure to include all dependencies in the `pkg_deps` of a `plan.ps1` to ensure all of their respective `DLL`s are accessible by your application. - -Most binaries compiled in a full Linux environment have a hard dependency on `/lib/ld-linux.so` or `/lib/ld-linux-x86_64.so`. In order to relocate this dependency to the Chef Habitat-provided variant, which is provided by `core/glibc`, use the `patchelf(1)` utility within your plan: - -1. Declare a build-time dependency on `core/patchelf` as part of your `pkg_build_deps` line. -2. Invoke `patchelf` on any binaries with this problem during the `do_install()` phase. For example: - -```bash -patchelf --interpreter "$(pkg_path_for core/glibc)/lib/ld-linux-x86-64.so.2" \ - "${pkg_prefix}/bin/somebinary" -``` - -3. The binary may have other hardcoded dependencies on its own libraries that you may need to relocate using other flags to `patchelf` like `--rpath`. For example, Oracle Java provides additional libraries in `lib/amd64/jli` that you will need to relocate to the Chef Habitat location: - -```bash -export LD_RUN_PATH=$LD_RUN_PATH:$pkg_prefix/lib/amd64/jli -patchelf --interpreter "$(pkg_path_for core/glibc)/lib/ld-linux-x86-64.so.2" \ - --set-rpath ${LD_RUN_PATH} "${pkg_prefix}/bin/java" -``` - -4. For more information, please see the [patchelf](https://nixos.org/patchelf.html) documentation. - -## Relocating library dependencies - -In some situations it will be impossible for you to relocate library dependencies using `patchelf` as above. For example, if the version of `glibc` the software requires is different than that provided by an available version of `glibc` in a Chef Habitat package, attempting to `patchelf` the program will cause execution to fail due to ABI incompatibility. - -Your software vendor's support policy might also prohibit you from modifying software that they ship you. - -In these situations, you will have to give up Chef Habitat's guarantees of complete dependency isolation and continue to rely on the library dependencies provided by the host operating system. However, you can continue to use the features of the Chef Habitat Supervisor that provide uniform manageability across your entire fleet of applications. - -## Fixing hardcoded interpreters - -Binary packages often come with other utility scripts that have their interpreter, or "shebang", line (first line of a script) hardcoded to a path that will not exist under Chef Habitat. Examples are: `#!/bin/sh`, `#!/bin/bash`, `#!/bin/env` or `#!/usr/bin/perl`. It is necessary to modify these to point to the Chef Habitat-provided versions, and also declare a runtime dependency in your plan on the corresponding Chef Habitat package (for example, `core/perl`). - -Use the `fix_interpreter` function within your plan to correct these interpreter lines during any phase, but most likely your `do_build` phase. For example: - -```bash -fix_interpreter ${target} core/coreutils bin/env -``` - -The arguments to `fix_interpreter` are the file (represented here by `${target}`) you are trying to fix, the origin/name pair of the Chef Habitat package that provides that interpreter, and the interpreter pattern to search and replace in the target. - -If you have many files you need to fix, or the binary package automatically generates scripts with hardcoded shebang lines, you may need to simply symlink Chef Habitat's version into where the binary package expects it to go: - -```bash -ln -sv $(pkg_path_for coreutils)/bin/env /usr/bin/env -``` - -This is a last resort as it breaks the dependency isolation guarantees of Chef Habitat. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/build_helpers.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/build_helpers.md deleted file mode 100644 index ba2e2fba1e..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/build_helpers.md +++ /dev/null @@ -1,249 +0,0 @@ -+++ -title = "Build Helpers" -description = "Define package buildtime actions with helper functions." -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Build Helpers" - identifier = "habitat/reference/build-helpers" - parent = "habitat/reference" - -+++ - -The following helper functions can be useful in your plan to help you build your package correctly. `Attach()` specifically is to help with debugging - the other helper functions are to help you in building your package. - -{{< note >}} -Most of the following helper functions are not available in Powershell plans (`plan.ps1`). However in most cases, the standard Powershell cmdlets provide the same functionality. For example: use `Resolve-Path` instead of `abspath` or `Get-Command` instead of `exists`. -{{< /note >}} - -attach() -: `plan.sh` only. Attaches your script to an interactive debugging session, which lets you check the state of variables, call arbitrary functions, and turn on higher levels of logging by using the `set -x` command and switch. - - To use attach, add `attach` to any callback or part of your plan.sh file and the debugging session with start up when hab-plan-build comes to that part in the file. - -{{< note >}} -Use the native Powershell cmdlet `Set-PSBreakpoint` for debugging plan.ps1 functions. You can set its `-Command` parameter to any build phase function. -{{< /note >}} - -download_file() -: `plan.sh` only. Downloads a file from a source URL to a local file and uses an optional -shasum to determine if an existing file can be used. - -```bash -download_file [] -``` - -If an existing file is present and the third argument is set with a shasum -digest, the file will be checked to see if it's valid. If so, the function -ends early and returns 0. Otherwise, the shasums do not match so the -file-on-disk is removed and a normal download proceeds as though no previous -file existed. This is designed to restart an interrupted download. - -Any valid `wget` URL will work. - -Downloads every time, even if the file exists locally: - -```bash -download_file http://example.com/file.tar.gz file.tar.gz -``` - -Downloads if no local file is found: - -```bash -download_file http://example.com/file.tar.gz file.tar.gz expected_shasum -``` - -File matches checksum: download is skipped, local file is used: - -```bash -download_file http://example.com/file.tar.gz file.tar.gz expected_shasum -``` - -File doesn't match checksum: local file removed, download attempted: - -```bash -download_file http://example.com/file.tar.gz file.tar.gz mismatching_shasum -``` - -Will return 0 if a file was downloaded or if a valid cached file was found. - -pkg\_path\_for()/Get-HabPackagePath -: Returns the path for a build or runtime package dependency on stdout from the list of dependencies referenced in `pkg_deps` or `pkg_build_deps`. This is useful if you need to install or reference specific dependencies from within a callback, such as `do_build()` or `do_install()`. - - Here's an example of how to use this function to retrieve the path to the perl binary in the core/perl package: - -```bash -_perl_path="$(pkg_path_for core/perl)/bin/perl" -``` - -fix_interpreter() -: `plan.sh` only. Edits the `#!` shebang of the target file in-place. This is useful for changing hard-coded paths defined by your source files to the equivalent path in a Chef Habitat package. You must include the required package that provides the expected path for the shebang in pkg_deps. This function performs a greedy match against the specified interpreter in the target file(s). - -To use this function in your plan, you must specify the following arguments: - - 1. The target file or files - 2. The name of the package that contains the interpreter - 3. The relative directory and binary path to the interpreter - -For example, to replace all the files in `node_modules/.bin` that have `#!/usr/bin/env` with the coreutils path to `bin/env` (/hab/pkgs/core/coreutils/8.24/20160219013458/bin/env), you must quote the wildcard target as shown below. - -```bash -fix_interpreter "node_modules/.bin/*" core/coreutils bin/env -``` - -For a single target, reference the file directly: - -```bash -fix_interpreter node_modules/.bin/concurrent core/coreutils bin/env -``` - -pkg\_interpreter\_for() -: `plan.sh` only. Returns the path for the given package and interpreter by reading it from the INTERPRETERS metadata in the package. The directory of the interpreter needs to be specified, as an interpreter binary might live in `bin`, `sbin`, or `libexec`, depending on the software. - -The following shows how to call pkg_interpreter_for with the package and interpreter arguments specified. - -```bash -pkg_interpreter_for core/coreutils bin/env -``` - -This function will return 0 if the specified package and interpreter were found, and 1 if the package could not be found or the interpreter is not specified for that package. - -pkg_version() -: An optional way to determine the value for `$pkg_version`. The function must print the computed version string to standard output and will be called when the Plan author invokes the `update_pkg_version()` helper in a `plan.sh` or `Set-PkgVersion` in a `plan.ps1`. - -update\_pkg\_version()/Set-PkgVersion -: Updates the value for `$pkg_version` by calling a Plan author-provided `pkg_version()` function. This function must be explicitly called in a Plan in or after the `do_before()`/`Invoke-Before` build phase but before the `do_prepare()`/`Invoke-Prepare` build phase. The `$pkg_version` variable will be updated and any other relevant variables will be recomputed. The following examples show how to use these functions to set a dynamic version number. - -This plan concatenates a static file in the source root of the -project to determine the version in the `before` phase: - -{{< foundation_tabs tabs-id="bash-powershell-panel1" >}} - {{< foundation_tab active="true" panel-link="bash-panel1" tab-text="Bash">}} - {{< foundation_tab panel-link="powershell-panel1" tab-text="Powershell" >}} -{{< /foundation_tabs >}} - -{{< foundation_tabs_panels tabs-id="bash-powershell-panel1" >}} - {{< foundation_tabs_panel active="true" panel-id="bash-panel1" >}} - ```bash - pkg_version() { - cat "$SRC_PATH/version.txt" - } - - do_before() { - do_default_before - update_pkg_version - } - ``` - {{< /foundation_tabs_panel >}} - - {{< foundation_tabs_panel panel-id="powershell-panel1" >}} - ```powershell - function pkg_version { - Get-Content "$SRC_PATH/version.txt" - } - - Invoke-Before { - Invoke-DefaultBefore - Set-PkgVersion - } - ``` - {{< /foundation_tabs_panel >}} -{{< /foundation_tabs_panels >}} - -The `pkg_version` function in this plan dynamically creates a version with a date stamp to format the final version string to standard output. -As the downloaded file is required before running the version logic, this helper function is called in the `download` build phase: - -{{< foundation_tabs tabs-id="bash-powershell-panel2" >}} - {{< foundation_tab active="true" panel-link="bash-panel2" tab-text="Bash">}} - {{< foundation_tab panel-link="powershell-panel2" tab-text="Powershell" >}} -{{< /foundation_tabs >}} - -{{< foundation_tabs_panels tabs-id="bash-powershell-panel2" >}} - {{< foundation_tabs_panel active="true" panel-id="bash-panel2" >}} - ```bash - pkg_version() { - local build_date - - # Extract the build date of the certificates file - build_date=$(cat $HAB_CACHE_SRC_PATH/$pkg_filename \ - | grep 'Certificate data from Mozilla' \ - | sed 's/^## Certificate data from Mozilla as of: //') - - date --date="$build_date" "+%Y.%m.%d" - } - - do_download() { - do_default_download - update_pkg_version - } - ``` - {{< /foundation_tabs_panel >}} - - {{< foundation_tabs_panel panel-id="powershell-panel2" >}} - ```powershell - function pkg_version { - # Extract the build date of the certificates file - $matchStr = "## Certificate data from Mozilla as of: " - foreach($line in (Get-Content "$HAB_CACHE_SRC_PATH/$pkg_filename")) { - if($line.StartsWith($matchStr)) { - $build_date = $line.Substring($matchStr.Length) - } - } - - [DateTime]::Parse($build_date).ToString("yyyy.mm.dd") - } - - function Invoke-Download { - Invoke-DefaultDownload - Set-PkgVersion - } - ``` - {{< /foundation_tabs_panel >}} -{{< /foundation_tabs_panels >}} - -abspath() -: `plan.sh` only. Return the absolute path for a path, which might be absolute or relative. - -exists() -: `plan.sh` only. Checks that the command exists. Returns 0 if it does, 1 if it does not. - -build_line()/Write-BuildLine -: Print a line of build output. Takes a string as its only argument. - -```bash -build_line "Checksum verified - ${pkg_shasum}" -``` - -warn()/Write-Warning -: Print a warning line on stderr. Takes a string as its only argument. - -```bash -warn "Checksum failed" -``` - -debug()/Write-Debug -: Prints a line only if the `$DEBUG` environment value is set to 1. The `debug` function takes a string as its only argument. - -```bash -DEBUG=1 -debug "Only if things are set" -``` - -exit_with() -: `plan.sh` only. Exits the program with an error message and a status code. - -```bash -exit_with "Something bad happened" 55 -``` - -trim() -: `plan.sh` only. Trims leading and trailing whitespace characters from a bash variable. - -record() -: `plan.sh` only. Takes a session name and command to run as arguments function appends a timestamp to the log file. Alternative to piping build through tee. - -```bash -# Usage: record [CMD [ARG ...]] -record mysoftware build /src/mysoftware -``` diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/build_phase_callbacks.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/build_phase_callbacks.md deleted file mode 100644 index 9708a768ff..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/build_phase_callbacks.md +++ /dev/null @@ -1,251 +0,0 @@ -+++ -title = "Build Phase Callbacks" -description = "Override default buildtime behavior with build phase callbacks" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Build Phase Callbacks" - identifier = "habitat/reference/build-phase-callbacks" - parent = "habitat/reference" -+++ - -When defining your plan, you can override the default behavior of Chef Habitat in each build phase through a callback. To define a callback, simply create a shell function of the same name in your plan file and then write your script. If you do not want to use the default callback behavior, you must override the callback and `return 0` in the function definition or simply provide no implementation in a `plan.ps1`. - -These callbacks are listed in the order that they executed by the package build script. - -{{< note >}} -Bash callbacks are prefixed with `do_` and use an underscore convention. Powershell plans prefix callbacks with `Invoke-` and use a PascalCase convention. -{{< /note >}} - -You can also use [plan variables]({{< relref "plan_variables" >}}) in your plans to place binaries, libraries, and files into their correct locations during package compilation or when running as a service. - -Additionally, [plan helper functions]({{< relref "build_helpers" >}}) can be useful in your plan to help you build your package correctly. They are mostly used for building packages - attach() is used for debugging. - -do_begin()/Invoke-Begin -: Used to execute arbitrary commands before anything else happens. Note that at this phase of the build, no dependencies are resolved, the `$PATH` and environment is not set, and no external source has been downloaded. For a phase that is more completely set up, see the `do_before()` phase. - -do_begin_default()/Invoke-BeginDefault -: There is an empty default implementation of this callback. - -do_setup_environment()/Invoke-SetupEnvironment -: Use this to declare buildtime and runtime environment variables that overwrite or are in addition to the default environment variables created by Chef Habitat during the build process. Examples of common environment variables you might wish to add or modify are those such as `JAVA_HOME` or `GEM_PATH`. - -{{< note >}} -You do not have to override this callback if you do not wish to modify your environment variables. The build system will always set up your environment according to your dependencies. For example, it will ensure that dependency binaries are always present on your `PATH` variable, and so on. -{{< /note >}} - -Runtime environments of dependencies are layered together in the order they are declared in your `pkg_deps` array, followed by modifications made in this callback. In turn, these computed values will be made available to packages that use the current package as a dependency, and so on. - -The buildtime environment is assembled by processing the *runtime* environments of your `pkg_build_deps` dependencies (because they will be running in your build) in a similar manner. The final environment in which your package will be built consists of: - -* The system environment of your Studio as the base layer -* The assembled runtime environment of your package on top of the base -* Any buildtime environment information on top of the assembled runtime environment - -Only the runtime portion of this combined buildtime environment is made available to your package when it is running in a Supervisor (or when it is being used as a dependency of another Chef Habitat package). - -To add or modify your environment variables, there are special functions to call within this callback to ensure that the variables are set up appropriately. - -{{< foundation_tabs tabs-id="bash-powershell-panel1" >}} - {{< foundation_tab active="true" panel-link="bash-panel1" tab-text="Bash">}} - {{< foundation_tab panel-link="powershell-panel1" tab-text="Powershell" >}} -{{< /foundation_tabs >}} - -{{< foundation_tabs_panels tabs-id="bash-powershell-panel1" >}} - {{< foundation_tabs_panel active="true" panel-id="bash-panel1" >}} - ```bash - set_runtime_env [-f] VARIABLE_NAME VALUE - set_buildtime_env [-f] VARIABLE_NAME VALUE - ``` - {{< /foundation_tabs_panel >}} - - {{< foundation_tabs_panel panel-id="powershell-panel1" >}} - ```powershell - Set-RuntimeEnv VARIABLE_NAME VALUE [-force] [-IsPath] - Set-BuildtimeEnv VARIABLE_NAME VALUE [-force] [-IsPath] - ``` - {{< /foundation_tabs_panel >}} -{{< /foundation_tabs_panels >}} - -In Powershell plans, if your variable contains values that are file paths pointing inside the Chef Habitat `/hab` directory, you can use the `-IsPath` flag to ensure that the path remains portable accross different Chef Habitat environments. For example in a local (non-Docker) Windows Studio, the following line: - -```powershell -Set-RuntimeEnv SSL_CERT_FILE "$(Get-HabPackagePath cacerts)/ssl/cert.pem" -``` - -will set `SSL_CERT_FILE` to the `ssl/cert.pem` file inside of the `cacerts` package path. This path will be located inside of `c:/hab/studios` which will not be valid inside of a non-Studio Supervisor or inside of a Docker Studio. Instead, use the following code: - -```powershell -Set-RuntimeEnv SSL_CERT_FILE "$(Get-HabPackagePath cacerts)/ssl/cert.pem" -IsPath -``` - -This will hint to the packaging system that this path should be properly rooted inside of the Chef Habitat filesystem of the current running environment. - -These functions allow you to _set_ an environment variable's value. If one of your dependencies has already declared a value for this, it will result in a build failure, protecting you from inadvertently breaking anything. If you really do want to replace the value, you can supply the `-f` or `-force` flag. - -For pushing new values onto a multi-valued environment variable (like `PATH`), use the following functions: - -{{< foundation_tabs tabs-id="bash-powershell-panel2" >}} - {{< foundation_tab active="true" panel-link="bash-panel2" tab-text="Bash">}} - {{< foundation_tab panel-link="powershell-panel2" tab-text="Powershell" >}} -{{< /foundation_tabs >}} - -{{< foundation_tabs_panels tabs-id="bash-powershell-panel2" >}} - {{< foundation_tabs_panel active="true" panel-id="bash-panel2" >}} - ```bash - push_runtime_env VARIABLE_NAME VALUE - push_buildtime_env VARIABLE_NAME VALUE - ``` - {{< /foundation_tabs_panel >}} - - {{< foundation_tabs_panel panel-id="powershell-panel2" >}} - ```powershell - Push-RuntimeEnv VARIABLE_NAME VALUE [-IsPath] - Push-BuildtimeEnv VARIABLE_NAME VALUE [-IsPath] - ``` - {{< /foundation_tabs_panel >}} -{{< /foundation_tabs_panels >}} - -These functions allow you to push a new value onto a multi-valued environment variable without overwriting the existing values. These multi-valued variables are referred to as "aggregate" variables in Chef Habitat. Single-value environment variables are known as "primitive" variables. - -By default, Chef Habitat treats all variables as "primitive" variables. If you are working with a value that is actually an "aggregate" type, you must set the following special environment variable somewhere in the top level of your plan. - -{{< foundation_tabs tabs-id="bash-powershell-panel3" >}} - {{< foundation_tab active="true" panel-link="bash-panel3" tab-text="Bash">}} - {{< foundation_tab panel-link="powershell-panel3" tab-text="Powershell" >}} -{{< /foundation_tabs >}} - -{{< foundation_tabs_panels tabs-id="bash-powershell-panel3" >}} - {{< foundation_tabs_panel active="true" panel-id="bash-panel3" >}} - ```bash - export HAB_ENV_FOO_TYPE=aggregate - ``` - {{< /foundation_tabs_panel >}} - - {{< foundation_tabs_panel panel-id="powershell-panel3" >}} - ```powershell - $env:HAB_ENV_FOO_TYPE="aggregate" - ``` - {{< /foundation_tabs_panel >}} -{{< /foundation_tabs_panels >}} - -Similarly, Chef Habitat defaults to using the colon (`:`) as a separator for aggregate variables on Linux. If the hypothetical `FOO` variable uses a semicolon (`;`) as a separator instead, then you must add `export HAB_ENV_FOO_SEPARATOR=;` at the top level of the plan. On Windows, `;` is the default separator. - -In all cases, when Chef Habitat is assuming a default strategy, it will emit log messages to notify you of that along with instructions on how to change the behavior. - -{{< note >}} -If you discover common environment variables that Chef Habitat doesn't currently treat appropriately, feel free to request an addition to the codebase, or even to submit a pull request yourself. -{{< /note >}} - -do_before()/Invoke-Before -: At this phase of the build, the origin key has been checked for, all package dependencies have been resolved and downloaded, and the `$PATH` and environment are set, but this is just before any source downloading would occur (if `$pkg_source` is set). This could be a suitable phase in which to compute a dynamic version of a package given the state of a Git repository, fire an API call, start timing something, etc. - -do_before_default()/Invoke-BeforeDefault -: There is an empty default implementation of this callback. - -do_download()/Invoke-Download -: If `$pkg_source` is being used, download the software and place it in `$HAB_CACHE_SRC_PATH/$pkg_filename`. If the source already exists in the cache, verify that the checksum is what we expect, and skip the download. Delegates most of the implementation to the `do_default_download()` function. - -do_download_default()/Invoke-DownloadDefault -: The default implementation is that the software specified in `$pkg_source` is downloaded, checksum-verified, and placed in `$HAB_CACHE_SRC_PATH/$pkg_filename`, which resolves to a path like `/hab/cache/src/filename.tar.gz`. You should override this behavior if you need to change how your binary source is downloaded, if you are not downloading any source code at all, or if you are cloning from git. If you do clone a repo from git, you must override do_verify() to return 0. - -do_verify()/Invoke-Verify -: If `$pkg_source` is being used, verify that the package we have in `$HAB_CACHE_SRC_PATH/$pkg_filename` has the `$pkg_shasum` we expect. Delegates most of the implementation to the `do_default_verify()` function. - - If you do clone a repo from git, you must override do_verify() to return 0. - -do_verify_default()/Invoke-VerifyDefault -: The default implementation tries to verify the checksum specified in the plan against the computed checksum after downloading the source tarball to disk. If the specified checksum doesn't match the computed checksum, then an error and a message specifying the mismatch will be printed to stderr. You should not need to override this behavior unless your package does not download any files. - -do_clean()Invoke-Clean -: Clean up the remnants of any previous build job, ensuring it can't pollute out new output. Delegates most of the implementation to the `do_default_clean()` function. - -do_default_clean()/Invoke-DefaultClean -: The default implementation removes the `HAB_CACHE_SRC_PATH/$pkg_dirname` folder in case there was a previously-built version of your package installed on disk. This ensures you start with a clean build environment. - -do_unpack()/Invoke-Unpack -: If `$pkg_source` is being used, we take the `$HAB_CACHE_SRC_PATH/$pkg_filename` from the download step and unpack it,as long as the method of extraction can be determined. This takes place in the $HAB_CACHE_SRC_PATH directory. Delegates most of the implementation to the `do_default_unpack()` function. - -do_default_unpack()/Invoke-DefaultUnpack -: The default implementation extracts your tarball source file into `HAB_CACHE_SRC_PATH`. The supported archive extensions on Linux are: .tar, .tar.bz2, .tar.gz, .tar.xz, .rar, .zip, .Z, .7z. Only .zip is supported on Windows. If the file archive could not be found or has an unsupported extension, then a message will be printed to stderr with additional information. - -do_prepare()/Invoke-Prepare -: There is no default implementation of this callback. At this point in the build process, the tarball source has been downloaded, unpacked, and the build environment variables have been set, so you can use this callback to perform any actions before the package starts building, such as exporting variables, adding symlinks, and so on. - - A step that exists to be overridden. Do what you need to do before we actually run the build steps. - -do_default_prepare()/Invoke-DefaultPrepare -: There is an empty default implementation of this callback. - -do_build()/Invoke-Build -: You should override this behavior if you have additional configuration changes to make or other software to build and install as part of building your package. This step builds the software; assumes the GNU pattern. Delegates most of the implementation to the `do_default_build()` function. - -do_default_build()/Invoke-DefaultBuild -: The default implementation is to update the prefix path for the configure script to use `$pkg_prefix` and then run `make` to compile the downloaded source. This means the script in the default implementation does `./configure --prefix=$pkg_prefix && make`. - -do_check()/Invoke-Check -: Will run post-compile tests and checks, provided 2 conditions are true: - -1. A `do_check()` function has been declared. By default, no such function exists, so Plan author must add one explicitly--there is no reasonably good default here. -1. A `$DO_CHECK` environment variable is set to some non-empty value. As tests can dramatically inflate the build time of a Plan, this has been left as an opt-in option. - - Here's an example of a vanilla Plan such as `sed`: - - ```bash - core-plans/sed/plan.sh - pkg_name=sed - # other Plan metadata... - - do_check() { - make check - } - ``` - -do_install()/Invoke-Install -: Installs the software. Delegates most of the implementation to the `do_default_install()` function. You should override this behavior if you need to perform custom installation steps, such as copying files from `HAB_CACHE_SRC_PATH` to specific directories in your package, or installing pre-built binaries into your package. - -do_default_install()/Invoke-DefaultInstall -: The default implementation is to run `make install` on the source files and place the compiled binaries or libraries in `HAB_CACHE_SRC_PATH/$pkg_dirname`, which resolves to a path like `/hab/cache/src/packagename-version/`. It uses this location because of do_build() using the `--prefix` option when calling the configure script. - -do_build_config()/Invoke-BuildConfig -: Copy the `./config` directory, relative to the Plan, to `$pkg_prefix/config`. Do the same with `default.toml`. Delegates most of the implementation to the `do_default_build_config()` function. - - Allows users to depend on a core plan and pull in its configuration but set their own unique configurations at build time. - -do_default_build_config()/Invoke-DefaultBuildConfig -: Default implementation for the `do_build_config()` phase. - -do_build_service()/Invoke-BuildService -: Write out the `$pkg_prefix/run` file. If a file named `hooks/run` exists, we skip this step. Otherwise, we look for `$pkg_svc_run`, and use that. We assume that the binary used in the `$pkg_svc_run` command is set in the $PATH. - - This will write a `run` script that uses `chpst` to run the command as the `$pkg_svc_user` and `$pkg_svc_group`. These are `hab` by default. - - Delegates most of the implementation to the `do_default_build_server()` function. - -do_default_build_service()/Invoke-DefaultBuildService -: Default implementation of the `do_build_service()` phase. - -do_strip() -: `plan.sh` only. You should override this behavior if you want to change how the binaries are stripped, which additional binaries located in subdirectories might also need to be stripped, or whether you do not want the binaries stripped at all. - -do_default_strip() -: `plan.sh` only. The default implementation is to strip any binaries in `$pkg_prefix` of their debugging symbols. Goal of this step is to reduce our total size. - -do_after()/Invoke-After -: At this phase, the package has been built, installed, stripped, but before the package metadata is written and the artifact is created and signed. - -do_default_after()/Invoke-DefaultAfter -: There is an empty default implementation of this callback. - -do_end()/Invoke-End -: A function for cleaning up after yourself, this is called after the package artifact has been created. You can use this callback to remove any temporary files or perform other post-build clean-up actions. - -do_default_end()/Invoke-DefaultEnd -: There is an empty default implementation of this callback. - -do_after_success() -: `plan.sh` only. A function that is called at the absolute end of a successful build process. This can be used to provide integration points with external systems, among other things, particularly if you are not using Builder (a Notifications feature is coming to Builder in H2 2018). Failure of this callback will not fail your build, nor will it trigger a `do_after_failure` call. - -do_after_failure() -: `plan.sh` only. A function that is called at the absolute end of a failed build process. This can be used to provide integration points with external systems, among other things, particularly if you are not using Builder (a Notifications feature is coming to Builder in H2 2018). The result of this callback cannot affect the disposition of the overall build; once the build has failed, it's failed. Keep in mind that since a build could potentially fail at any time, certain variables or data structures may not be present or initialized when this callback is called, so code accordingly. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_api.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_api.md deleted file mode 100644 index dcd746bc7b..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_api.md +++ /dev/null @@ -1,17 +0,0 @@ -+++ -title = "Chef Habitat Builder API" -aliases = ["/habitat/api/builder-api/"] -date = 2019-03-06T17:25:30-07:00 -draft = false -layout = "data-api" -style_sheet = "/habitat-api-styles.css" -api_file_path = "/habitat-api-docs/builder-api.json" -return_page = "/habitat/" -description = "Chef Habitat Builder API documentation." - -[menu] - [menu.habitat] - title = "Builder API" - parent = "habitat/reference/api" - identifier = "habitat/reference/api Builder API" -+++ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_architecture.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_architecture.md deleted file mode 100644 index 5d9680f34a..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_architecture.md +++ /dev/null @@ -1,14 +0,0 @@ -+++ -title = "Chef Habitat Builder Architecture" -description = "Chef Habitat Builder Architecture" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Chef Habitat Builder Architecture" - identifier = "habitat/diagrams/builder-architecture" - parent = "habitat/diagrams" - weight = 90 - -+++ -![Chef Habitat Builder Architecture Diagram](/images/habitat/habitat-builder-architecture.png) diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_origin_packages.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_origin_packages.md deleted file mode 100644 index bca034f8d7..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_origin_packages.md +++ /dev/null @@ -1,198 +0,0 @@ -+++ -title = "Upload and Promote Packages" -description = "Upload and Promote packages on Chef Habitat Builder enables automated package rebuilds and increases collaboration" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Origin Packages" - identifier = "habitat/builder/origin-packages" - parent = "habitat/builder" - weight = 40 -+++ - -While you can build and run Chef Habitat packages without sharing them on [Chef Habitat Builder](https://bldr.habitat.sh), uploading them there enables greater collaboration and automated package rebuilds as underlying dependencies or your connected GitHub repository are updated. - -> Note: Chef Habitat Builder can only build Linux based plans (`plan.sh`) at this time. - -Setting up Chef Habitat Builder is easily done on the website: these steps take you through connecting your local Studio development experience with Builder. - -You interact with Chef Habitat Builder by: - -* Creating an account. -* Creating an origin, or being invited to join an origin that already exists. -* Setting up `hab` to authenticate with Builder. -* Uploading the private and public keys for that origin. -* Connecting your Github repositories and opting into rebuilds. - -Chef Habitat Builder supports both public and private origins, packages, and Github repositories. - -## Create a Builder Account - -If you haven't created an account yet, see the [Create a Builder Account]({{< relref "builder_account" >}}) section above. - -## Create or Join an Existing Origin - -You can create your own origin in Builder or be invited to join an existing one. If you already built some Chef Habitat packages on your local computer prior to signing up for an account, you must rename your local packages' `pkg_origin` if the origin you want already exists. - -## Set up Chef Habitat to Authenticate to Builder - -When you upload a package to Builder, you are required to supply an auth token as part of the `hab pkg upload` subcommand. You can generate a Chef Habitat personal access token via the Builder site [Profile page](https://bldr.habitat.sh/#/profile) for use with the `hab` command-line utility. - -Once you have this token, you can set the `HAB_AUTH_TOKEN` [environment variable]({{< relref "environment_variables" >}}) to this value, so that any commands requiring authentication will use it. - -## Create an Origin Key Pair - -After finishing the basic account creation steps, you need to create your origin key pair. Habitat will use the private origin key to sign the artifacts (`.hart` files) created by building your plan and verify the integrity of your artifacts with the public origin key. - -You can create an origin key pair by running `hab cli setup` from your host machine, or by running `hab origin key generate ` from either the host machine or from within the studio. - -Your public and private origin keys are located at `~/.hab/cache/keys` on your host machine and at `/hab/cache/keys` inside the studio environment. - -## Upload Your Origin Keys - -If you created a new Habitat origin from your host machine or from the Studio, Builder will not have either of the origin keys corresponding to your artifact. Builder will not accept uploaded artifacts without first having the correct public origin key. - -You can upload keys for the origin through the web interface for Builder, or by using the `hab origin key upload` command. You must have the access token for authentication, as described earlier, before you can upload keys. - -## Upload Packages to Builder - -As long as you are already a member of the Habitat origin, once Builder possesses at least the public origin key, then you may upload one or more artifacts to that origin with the `hab pkg upload` command. After Habitat validates the cryptographic integrity of the artifact, it is then uploaded and stored on Builder. Uploading artifacts is a privileged operation for which you must have the access token. - -## Promote Packages - -By default, newly uploaded packages are placed in the `unstable` channel. However, the default package that is downloaded is the latest `stable` version of a package, unless overridden in commands such as `hab sup run`, `hab svc load`, and `hab pkg install`. If you want to promote your package to the `stable` channel, run the `hab pkg promote` command as follows: - -```bash -$ hab pkg promote -z origin/package/version/release stable -``` - -> **Note** You can also promote packages to the `stable` channel using the *promote to stable* button in the web app. - -For more information on how to use channels, see [Continuous Deployment Using Channels]({{< relref "pkg_promote" >}}). - -### Running Packages from Builder - -> **Note:** When running private packages from Builder, it's necessary to add your [Chef Habitat access token]({{< relref "builder_profile#create-a-personal-access-token" >}}) to the machine where you intend to deploy the package, via `export HAB_AUTH_TOKEN=`. - -You can instruct the Supervisor to download and run packages from Builder by using the `hab sup` and `hab svc` commands, for example: - -```bash -$ hab sup run -$ hab svc load core/postgresql -``` - -If the Supervisor does not have the `core/postgresql` package in its local cache, it will contact Builder, retrieve the latest version and the public key for the `core` origin, verify the cryptographic integrity of the package, and then start it. - -You may also supply a `--channel` argument to instruct the Supervisor to use a different channel for the purposes of continuous deployment: - -```bash -$ hab svc load core/postgresql --channel unstable -``` - -### Running Packages from Exported Tarballs - -An exported tarball package contains the Chef Habitat client/binary as well as dependencies specified by your artifact. - -After deploying the tarball to your target server, extract the contents to the root filesystem (`/`): - -```bash -$ tar zxf core-nginx-1.11.10-20170616000025.tar.gz --directory / -``` - -You can instruct the Supervisor to run packages from an exported tarball: - -```bash -$ /hab/bin/hab svc start core/nginx -``` - -Note: On a clean server, this will download additional packages to satisfy the Supervisor dependencies. You will also require a `hab` group and `hab` user on the system for most services. - -## Building Packages with Multiple Plans - -If you have a GitHub repository with multiple components inside, you will most likely also have individual plans for those components that are located inside of component subfolders. By default, Builder will only look for a package plan in either the root of the repository, or in a `habitat` subfolder at the root. If it does not find a plan file in those locations, it will not automatically issue builds when it detects file changes in the repository. - -In order to tell Builder about the location of the individual plan files, and in order provide more fine-grained control over when component packages are built, you can programmatically customize how and when Builder will build your plans by specifying build behavior in a `.bldr.toml` file at the root of the repository that you connect to Builder. - -Using this file, Builder only builds packages when source files or directories are updated in paths specified in `.bldr.toml`. This allows you to configure the building, publishing, and post-processing phases of a plan build in Builder. - -To enable this functionality, do the following: - -1. Create a `.bldr.toml` in the root of your repository. - -2. Open it and add an entry for each component package that you want to build. - - The `.bldr.toml` file is in TOML format, so create a TOML table specifying the `$pkg_name` value for that plan and then add a `plan_path` field specifying the path to your `plan.sh` file (you do not need to include plan.sh explicitly in the path). If all the files related to the plan are under the plan path, then you are done. Otherwise, you will need an additional 'paths' field specifying Unix-style path globs to files that are associated with the plan you specified in the 'plan_path'. File or directory changes made in these path locations determine which packages will be rebuilt. Basically, when a file is committed, Builder will check to see whether it falls underneath the `plan_path` hierarchy, or matches one of the globs in the `paths` field if it was specified - if the answer is yes, then Builder will issue a build for that commit. - - It's important to note that the entries for `plan_path` and `paths` do not behave the same. If you have something like `plan_path = "habitat"`, that behaves as if you had written `plan_path = "habitat/*"` - that is, it will automatically check every file under the `habitat` directory. However, if you have something like `paths = [ "src" ]`, that is _not_ automatically expanded to `src/*`. That line will only watch for changes to a file called `src`. If you're wanting to watch for changes to any file inside the `src` directory, then you must explicitly specify the glob, like so: `paths = [ "src/*" ]`. - - For example, in the Chef Habitat repository itself, this TOML states that the `hab-launcher`, `hab-studio`, and `hab-sup` packages will be rebuilt if there are any changes in any of the specified `components` sub-directories. Note that `hab-studio` does not need to specify a `path` because all of it's files are within the `plan_path` hierarchy, but that is not the case for the other projects. - - ```toml - # .bldr.toml - [hab-launcher] - plan_path = "components/launcher/habitat" - paths = [ - "components/launcher/*", - "components/launcher-protocol/*", - "support/ci/builder-base-plan.sh", - ] - - [hab-studio] - plan_path = "components/studio" - - [hab-sup] - plan_path = "components/sup" - paths = [ - "components/sup/*", - "components/eventsrv-client/*", - "components/launcher-client/*", - "components/butterfly/*", - "components/core/*", - "components/builder-depot-client/*", - ] - ``` - - Notice that in order to specify that we're interested in all files inside of the directories in our `paths` entries, we had to add the `/*` glob to the end manually. - - It's also worth pointing out that there are multiple wildcard characters you can use when specifying path components. - -* `?` will match any single character. -* `*` will match any (possibly empty) sequence of characters -* `**` matches the current directory and arbitrary subdirectories. This sequence must form a single path component, so both `**a` and `b**` are invalid. More than two consecutive `*` characters is also invalid. -* `[...]` matches any character inside the brackets. You can also specify a range, such as `[0-9]` to match any digit or `[a-z]` to match any lowercase letter. -* `[!...]` is the negation of `[...]` so it will match any character *not* in the brackets. - - Note that while the above set of rules bears a remarkable resemblance to regular expressions, we do not support full regular expression syntax. Only what's shown here is supported. Here is an example. - - ```toml - # .bldr.toml - [hab-sup] - plan_path = "components/sup" # automatically checks every file inside the 'sup' directory - paths = [ - "components/sup/?", # matches any file with a single character file name inside the 'sup' directory - "components/eventsrv-client/*", # matches any file inside the 'eventsrv-client' directory - "components/launcher-client/**/*", # matches any file inside the 'launcher-client' directory and also any of its sub-directories - "components/butterfly/[0-9]*" # matches any file inside the 'butterfly' directory that begins with a number - ] - ``` - -## Automated Builds - -By connecting a plan file in Chef Habitat Builder, you can trigger both manual (via the web UI, or via the `hab` command line) as well as automated package rebuilds whenever a change is merged into the `master` branch of the repository containing your Chef Habitat plan, or when a dependent package updates (rebuilds). - -### Connect a Plan - -To connect a plan to Builder, view one of your origins (while signed in), click the **Connect a plan file** button, and complete the following steps: - - - Install the Builder GitHub App - - Choose the GitHub organization and repository containing your Chef Habitat plan - - Choose a privacy setting for the package - - Specify container-registry publishing settings (optional) - - Specify auto-build option (default is off) - -### Auto-build Option - -The auto-build option controls whether or not your package will get automatically re-built. This option is a useful capability to have - for example, if you have a demo app that doesn't need to be kept constantly up to date when some underlying dependency updates. Auto-build encompasses both builds that are triggered by Github web hooks (on commits to master), as well as builds that are triggered by a dependency updating. - -By default, new plan connections will have auto-build turned off. 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 deleted file mode 100644 index 53dce2239a..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_origins.md +++ /dev/null @@ -1,28 +0,0 @@ -+++ -title = "Create an Origin on Builder" -description = "Create an Origin on Builder" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Origins" - identifier = "habitat/builder/origins" - parent = "habitat/builder" - weight = 30 -+++ - -{{< readfile file="/habitat/reusable/md/builder_origins.md" >}} - -## 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 on-prem Habitat Builder deployment. - -## Where can I create an origin - -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/certs_custom.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/certs_custom.md deleted file mode 100644 index 9c6f79e8fd..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/certs_custom.md +++ /dev/null @@ -1,31 +0,0 @@ -+++ -title = "Custom Certificates" -description = "Handling custom (CA) certificates" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Custom Certificates" - identifier = "habitat/reference/certs-custom Custom Certs" - parent = "habitat/reference" -+++ - -Many enterprise environments use custom certificates (for example, self-signed). For example, an on-premises Chef Habitat Builder Depot might have a self-signed SSL certificate. - -Attempting to perform an operation using the Habitat client to communicate with a service that has a custom certificate can produce an error, such as: - -```output -✗✗✗ -✗✗✗ the handshake failed: The OpenSSL library reported an error: error:14090086:SSL routines:ssl3_get_server_certificate:certificate verify failed:s3_clnt.c:1269:: unable to get local issuer certificate -✗✗✗ -``` - -One option to remediate this error is to define a `SSL_CERT_FILE` environment variable pointing to the custom certificate path before performing the client operation. - -The Habitat 0.85.0 release in September 2019 improved the handling of custom certificates. -Now Habitat knows to look for custom certificates in the `~/.hab/cache/ssl` directory, which is `/hab/cache/ssl` when you are running as root. -Copying multiple certificates--for example, a self-signed certificate and a custom certificate authority certificate--to the Chef Habitat cache directory makes them automatically available to the Habitat client. - -The `/hab/cache/ssl` directory is also available inside a Habitat Studio. As long as the certificates are inside the cache directory before you enter the Studio, you'll also find them inside the Studio. In addition, if you've set the `SSL_CERT_FILE` environment variable, you'll also find both it and the file that it points to inside the Studio`/hab/cache/ssl` directory. - -Note: The `cert.pem` file name is reserved for Habitat. Do not use `cert.pem` as a file name when copying certs into the cache directory. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/config_templates.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/config_templates.md deleted file mode 100644 index 17187469e0..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/config_templates.md +++ /dev/null @@ -1,54 +0,0 @@ -+++ -title = "Configuration Templates" -description = "Using templates and tags to tune your application configuration files" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Configuration Templates" - identifier = "habitat/reference/configuration-templates Customize Chef Habitat Packages Configuration" - parent = "habitat/reference" - -+++ - -Chef Habitat allows you to templatize your application's native configuration files using [Handlebars](https://handlebarsjs.com/) syntax. The following sections describe how to create tunable configuration elements for your application or service. - -Template variables, also referred to as tags, are indicated by double curly braces: `{{a_variable}}`. In Chef Habitat, tunable config elements are prefixed with `cfg.` to indicate that the value is user-tunable. - -Here's an example of how to make a configuration element user-tunable. Assume that we have a native configuration file named `service.conf`. In `service.conf`, the following configuration element is defined: - -```conf -recv_buffer 128 -``` - -We can make this user tunable like this: - -```handlebars -recv_buffer {{cfg.recv_buffer}} -``` - -Chef Habitat can read values that it will use to render the templatized config files in three ways: - -1. `default.toml` - Each plan includes a `default.toml` file that specifies the default values to use in the absence of any user provided inputs. These files are written in [TOML](https://github.com/toml-lang/toml), a simple config format. -1. At runtime - Users can alter config at runtime using `hab config apply`. The input for this command also uses the TOML format. -1. Environment variable - At start up, tunable config values can be passed to Chef Habitat using environment variables. - -{{< note >}} -When building packages you should prefer supplying values in `default.toml`, then at runtime, and last in Environment variables. Environment variables override default.toml, and runtime config setting using `hab config apply` overrides both default settings and settings provided in environment variables. - -Changing settings using environment variables requires you to restart the supervisor in order to pick up the new or changed environment variable. -{{< /note >}} - -Here's what we'd add to our project's `default.toml` file to provide a default value for the `recv_buffer` tunable: - -```toml -recv_buffer = 128 -``` - -All templates located in a package's `config` folder are rendered to a config directory, `/hab/svc//config`, for the running service. The templates are re-written whenever configuration values change. -The path to this directory is available at build time in the plan as the variable `$pkg_svc_config_path` and available at runtime in templates and hooks as `{{pkg.svc_config_path}}`. - -All templates located in a package's `config_install` folder are rendered to a config_install directory, `/hab/svc//config_install`. These templates are only accessible to the execution of an `install` hook and any changes to the values referenced by these templates at runtime will not result in re-rendering the template. -The path to this directory is available at build time in the plan as the variable `$pkg_svc_config_install_path` and available at runtime in templates and `install` hooks as `{{pkg.svc_config_install_path}}`. - -Chef Habitat not only allows you to use Handlebars-based tunables in your plan, but you can also use both built-in Handlebars helpers as well as Chef Habitat-specific helpers to define your configuration logic. See [Reference]({{< relref "build_helpers" >}}) for more information. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/configuration_management.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/configuration_management.md deleted file mode 100644 index bd9ff36cf8..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/configuration_management.md +++ /dev/null @@ -1,24 +0,0 @@ -+++ -title = "Configuration Management" -description = "Configuration Management" -draft = false -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Configuration Management" - identifier = "habitat/reference/configuration-management" - parent = "habitat/reference" - -+++ -**Examples: [Ansible](https://www.ansible.com/), [Chef](https://www.chef.io/products/chef-infra), [Puppet](https://puppet.com/), and [Salt](https://saltstack.com/)** - -Configuration management tools allow you write configuration files, using a declarative language to manage a server. These tools focus on building working servers by installing and configuring system settings, system libraries, and application libraries before an application is installed on the server. Chef Habitat focuses on the application first instead of the server. Chef Habitat builds and packages your application's entire binary toolchain, including the system libraries, application libraries, and runtime dependencies necessary for your application to function. As a result, Chef Habitat can replace many use-cases that configuration management tools perform related to installing system binaries, application dependent libraries, or templating configuration files. - -Configuration management tools perform tasks at run time by converging resources. The value from configuration management tools comes from this converging process -- checking the existing state of a server, and fixing it if it does not match the intended state. Because converging modifies resources at runtime, it can result in surprising and complex runtime errors. In addition, since environments are often mutable and unique, maintaining server automation occurs out-of-band with application development, creating conflict between application developers and software reliability engineers. Chef Habitat avoids these classes of errors entirely by shifting these processes to build time, and by creating an atomic package of an application's binaries, application lifecycle hooks, and configuration files. Chef Habitat's approach to packaging automation with the application package allows application developers and software reliability engineers to work closer together. - -Chef Habitat is not a full replacement for configuration management tools on mutable infrastructure. Instead, it allows configuration management tools to focus better on system-level tasks for virtual machines and bare metal, such as kernel tuning, system hardening tasks, and compliance remediation tasks. Chef Habitat can then take over application automation roles, which results in a significant reduction in automation complexity for both infrastructure-focused automation and application-focused automation. - -Chef Habitat can make it easier to run your existing configuration management tool. You can create a Chef Habitat package of your configuration management tool's agent and/or dependencies, and run it on your existing mutable infrastructure. The Chef Habitat Supervisor's responsibility is to update your configuration management tool's agent, while your configuration management tool can still perform its normal tasks. - -Chef Habitat can provide an easier transition from virtual machine or bare metal workloads to containers, without needing to rewrite a monolithic application into microservices all at once. In this scenario, you can run the [Chef Habitat Supervisor]({{< relref "sup" >}}) on your existing virtual machine or bare metal infrastructure as you migrate away from your configuration management tool. Then, when you're ready, you export your application to the container format of your choice using the [Chef Habitat Studio]({{< relref "pkg_build" >}}). While you migrate your applications and services, the [Chef Habitat Supervisor]({{< relref "sup" >}}) runs on your existing mutable infrastructure, and runs your existing configuration management tool. New packages that do not require configuration management can also run under the [Chef Habitat Supervisor]({{< relref "sup" >}}) on your existing mutable infrastructure. As a result, you can continue to verify the working state of your application as you incrementally migrate your services. This approach provides an alternative to the "all-or-nothing" migration many teams are faced with when moving workloads to containers. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/container_orchestration.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/container_orchestration.md deleted file mode 100644 index 7390e22b52..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/container_orchestration.md +++ /dev/null @@ -1,15 +0,0 @@ -+++ -title = "Container Orchestration" -description = "Container Orchestration with Chef Habitat" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Container Orchestration" - identifier = "habitat/containers/container-orchestration" - parent = "habitat/containers" - weight = 20 - -+++ - -Chef Habitat packages may be exported with the Supervisor directly into a [variety of container formats]({{< relref "pkg_exports" >}}), but frequently the container is running in a container orchestrator such as Kubernetes or Mesos. Container orchestrators provide scheduling and resource allocation, ensuring workloads are running and available. Containerized Chef Habitat packages can run within these runtimes, managing the applications while the runtimes handle the environment surrounding the application (ie. compute, networking, security). diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/containers.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/containers.md deleted file mode 100644 index 5bcfe72333..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/containers.md +++ /dev/null @@ -1,21 +0,0 @@ -+++ -title = "Chef Habitat and Containers" -description = "Chef Habitat and Containers" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Chef Habitat and Containers" - identifier = "habitat/containers/containers" - parent = "habitat/containers" - weight = 10 - -+++ -**Examples: [Docker](https://www.docker.com/) and [CoreOS](https://coreos.com/)** - -Containers enable you to build an immutable snapshot of your runtime environment, including your operating system, system libraries, application libraries, and application. The container is built with a CLI tool, and then pushed to a container-specific artifact repository, known as a container registry. Chef Habitat is not a container format and exports your application to the container format of your choice. - -Chef Habitat builds more secure containers by exporting your application and any of its runtime dependencies directly into the container. When you build your application with Chef Habitat, your application takes ownership of the entire toolchain of its runtime dependencies. As a result, you no longer have to rely on a large operating system and unnecessary system libraries. This enables you to include only the binaries your application uses inside your container, which can decrease your container size. By eliminating the need for a large operating system, you also avoid including binaries that an attacker could use, which further increases the security of your container. Visit the [Running Chef Habitat Containers]({{< relref "running_habitat_linux_containers" >}}) section of the docs to find more details about how containers are built with Chef Habitat. Finally, [Chef Habitat's HTTP API]({{< relref "monitor_services" >}}) allows all of your application's runtime dependencies to be audited at any time. If a brand new vulnerability is revealed, [Chef Habitat's HTTP API]({{< relref "monitor_services" >}}) makes it easy to programmatically inspect and audit the entire toolchain of your runtime environment without needing to worry about how your containers got built in the first place. - -If your situation requires it, Chef Habitat makes it simple to switch from containerized to non-containerized workloads. This is because Chef Habitat packages only have a requirement on the kernel version of your operating system. (Linux: kernel 2.6.32 or later, Windows: Windows Server 2008 R2 or later and Windows 7 64-bit or later). You can take the same .hart file you use to export to a Docker container and run it on a virtual machine or bare metal. By only requiring the kernel, Chef Habitat gives you the ability to switch container formats or to switch to non-containerized workloads without significant rework. - diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/continuous_integration.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/continuous_integration.md deleted file mode 100644 index a1b1ee4ad0..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/continuous_integration.md +++ /dev/null @@ -1,22 +0,0 @@ -+++ -title = "Chef Habitat and Continuous Integration" -description = "Chef Habitat and Continuous Integration" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Continuous Integration" - identifier = "habitat/packages/habitat-and-continuous-integration" - parent = "habitat/packages" - weight = 200 - -+++ - -**Examples: [Jenkins](https://jenkins.io/), [TravisCI](https://travis-ci.org/), and [Drone](https://drone.io/)** - -Continuous integration allows you to build, test, and deploy your code by using CLI tools and plugins. Chef Habitat includes the [Chef Habitat Studio]({{< relref "pkg_build" >}}) which allows you to do interactive builds on your developer workstation, or non-interactive builds with your continuous integration server. Your continuous integration server can also call the Chef Habitat CLI to promote your Chef Habitat packages to different channels, enabling your applications to update themselves. Chef Habitat is not a continuous integration server and can make builds and promotion processes done by your continuous integration server easier. - -The [Chef Habitat Studio]({{< relref "pkg_build" >}}) provides a clean room build environment for your application build. In effect, builds that occur on a developer's workstation, or on a continuous integration server, will build in the same manner. Developers no longer need to worry about entire classes of "it works on my box" problems. Build engineers no longer need to create unique and difficult to maintain worker nodes for continuous integration servers. Instead, the Chef Habitat plan.sh file contains all the information needed to build the entire application, from dependency management, runtime environment binaries, packaging, and application lifecycle hooks. When using the [Chef Habitat Studio]({{< relref "pkg_build" >}}), your continuous integration server can focus more on what it is good at doing, instead of worrying about managing custom plugins and their potential conflicts. - -Your continuous integration server can promote a Chef Habitat package (a .hart file) to a channel by calling the [Chef Habitat CLI]({{< relref "install_habitat" >}}). This promotion method allows you to deploy a new version of your application in a pull-based manner by using the Chef Habitat Supervisor. Because this promotion process can be invoked non-interactively through the [Chef Habitat CLI]({{< relref "install_habitat" >}}), you can manage your deployments using your existing tooling. If you choose, you can also do this promotion process manually. More complex application environments can also invoke the promotion process using a scheduling tool or provisioning tool to help manage infrastructure resources in addition to promoting Chef Habitat packages. - diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/dependency_update_flow.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/dependency_update_flow.md deleted file mode 100644 index 57505d6e5d..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/dependency_update_flow.md +++ /dev/null @@ -1,15 +0,0 @@ -+++ -title = "Dependency Update Flow" -description = "Dependency Update Flow" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Dependency Update Flow" - identifier = "habitat/diagrams/dependency-update-flow" - parent = "habitat/diagrams" - weight = 30 - -+++ -![Chef Habitat Dependency Update Flow Diagram](/images/habitat/habitat-dependency-update-flow.png) - diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/docker_automated_flow.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/docker_automated_flow.md deleted file mode 100644 index d6e2eb7816..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/docker_automated_flow.md +++ /dev/null @@ -1,15 +0,0 @@ -+++ -title = "Automate Docker Container Publishing Flow" -description = "Automate Docker Container Publishing Flow" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Automated Docker Container Publishing Flow" - identifier = "habitat/diagrams/docker-automated-flow" - parent = "habitat/diagrams" - weight = 60 - -+++ -![Chef Habitat Automated Docker Container Publishing Flow Diagram](/images/habitat/habitat-automated-docker-container-publishing-flow.png) - diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/docker_flow.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/docker_flow.md deleted file mode 100644 index 26a37be7f6..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/docker_flow.md +++ /dev/null @@ -1,14 +0,0 @@ -+++ -title = "Docker Container Publishing Flow" -description = "Docker Container Publishing Flow" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Docker Container Publishing Flow" - identifier = "habitat/diagrams/docker-flow" - parent = "habitat/diagrams" - weight = 50 - -+++ -![Chef Habitat Initial Docker Container Publishing Flow Diagram](/images/habitat/habitat-initial-docker-container-publishing-flow.png) diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/ecs.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/ecs.md deleted file mode 100644 index 61aecbab55..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/ecs.md +++ /dev/null @@ -1,58 +0,0 @@ -+++ -title = "Amazon ECS" -description = "Amazon ECS registry service and Chef Habitat" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Amazon Container Services (ECS)" - identifier = "habitat/containers/ecs EC2 Container Service" - parent = "habitat/containers" - weight = 50 - -+++ - -Amazon Web Services provides a container management service called [EC2 Container Service (ECS)](https://aws.amazon.com/ecs/). ECS provides a Docker registry, container hosting and tooling to make deploying Docker-based containers fairly straightforward. ECS will schedule and deploy your Docker containers within a Task while Chef Habitat manages the applications. - -## EC2 Container Registry - -[EC2 Container Registry (ECR)](https://aws.amazon.com/ecr/) is a fully-managed Docker registry provided by Amazon Web Services. Applications exported to Docker with ```hab pkg export docker``` put the containers into namespaced repositories, so you will need to create these within ECR. For example, if you were building ```core/mongodb``` containers you would use the following command: - -```bash -$ aws ecr create-repository --repository-name core/mongodb -``` - -To tag and push the images to the ECR you will use your Repository URI (substituting your **aws_account_id** and availability zone). - -```bash -$ docker tag core/mongodb:latest aws_account_id.dkr.ecr.ap-southeast-2.amazonaws.com/core/mongodb:latest -$ docker push aws_account_id.dkr.ecr.ap-southeast-2.amazonaws.com/core/mongodb:latest -``` - -## EC2 Compute Service - -Once Docker images are pushed to ECR, they may be run on Amazon's ECS within a [Task Definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_defintions.html) which may be expressed as a [Docker Compose file](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/cmd-ecs-cli-compose.html). Here is an example of a Tomcat application using a Mongo database demonstrating using Chef Habitat-managed containers: - -```yaml docker-compose.yml -version: '2' -services: - mongo: - image: aws_account_id.dkr.ecr.ap-southeast-2.amazonaws.com/username/mongodb:latest - hostname: "mongodb" - national-parks: - image: aws_account_id.dkr.ecr.ap-southeast-2.amazonaws.com/username/national-parks:latest - ports: - - "8080:8080" - links: - - mongo - command: --peer mongodb --bind database:mongodb.default -``` - -From the example, the ```mongo``` and ```national-parks``` services use the Docker images from the ECR. The ```links``` entry manages the deployment order of the container and according to the [Docker Compose documentation](https://docs.docker.com/engine/userguide/networking/default_network/dockerlinks/#/updating-the-etchosts-file) ```links``` should create ```/etc/hosts``` entries. This does not appear to currently work with ECS so we assign the ```hostname: "mongodb"```. - -The ```command``` entry for the National Parks Tomcat application allows the Chef Habitat Supervisor to ```--peer``` to the ```mongo``` gossip ring and ```--bind``` applies ```database``` entries to its Mongo configuration. - -## Related Reading - -* [A Journey with Chef Habitat on Amazon ECS, Part 1](https://www.chef.io/blog/a-journey-with-habitat-on-amazon-ecs-part-1) -* [A Journey with Chef Habitat on Amazon ECS, Part 2](https://www.chef.io/blog/a-journey-with-habitat-on-amazon-ecs-part-2) diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/environment_variables.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/environment_variables.md deleted file mode 100644 index d3743a7282..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/environment_variables.md +++ /dev/null @@ -1,52 +0,0 @@ -+++ -title = "Environment Variables" -description = "Customize and configure your Chef Habitat Studio and Supervisor environments" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Environment Variables" - identifier = "habitat/reference/environment-variables" - parent = "habitat/reference" - -+++ - -This is a list of all environment variables that can be used to modify the operation of the Chef Habitat Studio and Supervisor. - -| Variable | Context | Default | Description | -|----------|----------|----------|-----------| -| `HAB_AUTH_TOKEN` | build system | no default | Authorization token used to perform privileged operations against the depot, e.g. uploading packages or keys. -| `HAB_BINLINK_DIR` | build system | `/hab/bin` | Allows you to change the target directory for the symlink created when you run `hab pkg binlink`. The default value is already included in the `$PATH` variable inside the Studio. | -| `HAB_CACHE_KEY_PATH` | build system, Supervisor | `/hab/cache/keys` if running as root; `$HOME/.hab/cache/keys` if running as non-root | Cache directory for origin signing keys | -| `HAB_CTL_SECRET` | Supervisor | no default | Shared secret used for [communicating with a Supervisor]({{< relref "sup_remote_control" >}}). | -| `HAB_BLDR_CHANNEL` | build system, Supervisor | `stable` | Set the Chef Habitat Builder channel you are subscribing to, to a specific channel. Defaults to `stable`. -| `HAB_BLDR_URL` | build system, Supervisor | `https://bldr.habitat.sh` | Sets an alternate default endpoint for communicating with Builder. Used by the Chef Habitat build system and the Supervisor | -| `HAB_DOCKER_OPTS` | build system | no default | When running a Studio on a platform that uses Docker (macOS), additional command line options to pass to the `docker` command. | -| `HAB_INTERNAL_BLDR_CHANNEL` | build system, Supervisor, exporters | `stable` | Channel from which Chef Habitat-specific packages (e.g., `core/hab-sup`, `core/hab-launcher`, etc.) are downloaded on-demand when first called. Generally of use only for those developing Chef Habitat. Only applies to Chef Habitat-specific packages, and nothing else. | -| `HAB_LICENSE` | build system, Supervisor, exporters | no default | Used to accept the [Chef EULA]({{< relref "chef_license#chef-eula" >}}). See [Accepting the Chef License]({{< relref "chef_license_accept#habitat" >}}) for valid values. | -| `HAB_LISTEN_CTL` | Supervisor | 127.0.0.1:9632 | The listen address for the Control Gateway. This also affects `hab` commands that interact with the Supervisor via the Control Gateway, for example: `hab sup status`. | -| `HAB_LISTEN_GOSSIP` | Supervisor | 0.0.0.0:9638 | The listen address for the Gossip System Gateway | -| `HAB_LISTEN_HTTP` | Supervisor | 0.0.0.0:9631 | The listen address for the HTTP Gateway | -| `HAB_NOCOLORING` | build system | no default | If set to the lowercase string `"true"` this environment variable will unconditionally disable text coloring where possible | -| `HAB_NONINTERACTIVE` | build system | no default | If set to the lowercase string `"true"` this environment variable will unconditionally disable interactive progress bars (i.e. "spinners") where possible | -| `HAB_ORG` | Supervisor | no default | Organization to use when running with [service group encryption]({{< relref "sup_secure" >}}) -| `HAB_ORIGIN` | build system | no default | Origin used to build packages. The signing key for this origin is passed to the build system. | -| `HAB_ORIGIN_KEYS` | build system | no default | Comma-separated list of origin keys to automatically share with the build system | -| `HAB_REFRESH_CHANNEL` | build system | `stable` | Channel used to retrieve plan dependencies for Chef supported origins. | -| `HAB_RING` | Supervisor | no default | The name of the ring used by the Supervisor when running with [wire encryption]({{< relref "sup_secure" >}}) | -| `HAB_RING_KEY` | Supervisor | no default | The contents of the ring key when running with [wire encryption]({{< relref "sup_secure" >}}). Useful when running in a container. | -| `HAB_STUDIO_SECRET_` | build system | no default | Prefix to allow environment variables into the Studio. The prefix will be removed and your variable will be passed into the Studio at build time. | -| `HAB_STUDIOS_HOME` | build system | `/hab/studios` | Directory in which to create build Studios | -| `HAB_STUDIO_BACKLINE_PKG` | build system | `core/hab-backline/{{studio_version}}` | Overrides the default package identifier for the "backline" package which installs the Studio baseline package set. | -| `HAB_STUDIO_ROOT` | build system | no default | Root of the current Studio under `$HAB_STUDIOS_HOME`. Infrequently overridden. | -| `HAB_STUDIO_NOSTUDIORC` | build system | no default | When set to a non-empty value, a `.studiorc` will not be sourced when entering an interactive Studio via `hab studio enter`. | -| `HAB_STUDIO_SUP` | build system | no default | Used to customize the arguments passed to an automatically launched Supervisor, or to disable the automatic launching by setting it to `false`, `no`, or `0`. | -| `HAB_GLYPH_STYLE` | build system | `full` (`limited` on Windows) | Used to customize the rendering of unicode glyphs in UI messages. Valid values are `full`, `limited`, or `ascii`. | -| `HAB_SUP_UPDATE_MS` | Supervisor | 60000 | Interval in milliseconds governing how often to check for Supervisor updates when running with the [--auto-update]({{< relref "habitat_cli/#hab-sup-run" >}}) flag. Note: This variable has been deprecated. Users should instead use the [--auto-update-period]({{< relref "habitat_cli/#hab-sup-run" >}}) flag. | -| `HAB_UPDATE_STRATEGY_FREQUENCY_MS` | Supervisor | 60000 | Interval in milliseconds governing how often to check for service updates when running with an [update strategy]({{< relref "service_updates" >}}). Note: This variable has been deprecated. Users should instead use the [--service-update-period]({{< relref "habitat_cli/#hab-sup-run" >}}) flag. | -| `HAB_USER` | Supervisor | no default | User key to use when running with [service group encryption]({{< relref "sup_secure" >}}) | -| `http_proxy` | build system, Supervisor | no default | A URL for a local HTTP proxy server optionally supporting basic authentication | -| `https_proxy` | build system, Supervisor | no default | A URL for a local HTTPS proxy server optionally supporting basic authentication | -| `NO_INSTALL_DEPS` | build system | no default | Set this variable to prevent dependencies install during build | -| `no_proxy` | build system, Supervisor | no default | A comma-separated list of domain exclusions for the `http_proxy` and `https_proxy` environment variables | -| `SSL_CERT_FILE` | system | no default | Standard OpenSSL environment variable to override the system certificate file. This is particularly important for the secure HTTPS connection with a Builder instance. Can be used to help you navigate corporate firewalls. | diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/gcr.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/gcr.md deleted file mode 100644 index f523283105..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/gcr.md +++ /dev/null @@ -1,38 +0,0 @@ -+++ -title = "Google Container Registry (GCR)" -description = "Google Container Registry" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Google Container Registry (GCR)" - identifier = "habitat/containers/gcr GCR" - parent = "habitat/containers" - weight = 60 - -+++ -[Google Container Registry](https://cloud.google.com/container-registry/) is a private Docker repository that -works with popular continuous delivery systems. It runs on GCP to provide consistent uptime on an infrastructure -protected by Google's security. The registry service hosts your private images in Cloud Storage under your GCP project. - -Before you can push or pull images, you must configure Docker to use the gcloud command-line tool to authenticate -requests to Container Registry. To do so, run the following command (you are only required to do this once): - -```bash -$ gcloud auth configure-docker -``` - -Further access control information is [available here](https://cloud.google.com/container-registry/docs/access-control). - -After a successful Chef Habitat package build, images can be pushed to the Container Registry using the registry URI. The format of this -follows: `[HOSTNAME]/[PROJECT-ID]/[IMAGE]:[TAG]`, more details at [this link](https://cloud.google.com/container-registry/docs/pushing-and-pulling): - -```bash -$ hab pkg export docker ./results/habskp-hab-gcr-demo-0.1.0-20180710145742-x86_64-linux.hart -$ docker tag habskp/hab-gcr-demo:latest eu.gcr.io/user-project/hab-gcr-demo:latest -$ docker push eu.gcr.io/user-project/hab-gcr-demo:latest -``` - -## Related Reading - -* [Google Container Registry](https://cloud.google.com/container-registry/) diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/get_started.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/get_started.md deleted file mode 100644 index 1b322b29e9..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/get_started.md +++ /dev/null @@ -1,244 +0,0 @@ -+++ -title = "Get Started with Chef Habitat" -gh_repo = "habitat" -draft = true - -[menu] - [menu.habitat] - title = "Get Started" - identifier = "habitat/get_started" - parent = "habitat" - weight = 5 -+++ - -This getting started guide will show you how to use Chef Habitat to build and deploy a Node.js application. - -## Prerequisites - -Before getting started with this tutorial, you will need: - -- a workstation running Linux or macOS -- a [GitHub account](https://github.com/join) -- [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed locally (optional) -- the [Chef Habitat CLI]({{< relref "/habitat/install_habitat" >}}) installed locally -- an account on [Chef Habitat Builder]({{< relref "builder_account" >}}) -- a [profile on your Builder account]({{< relref "builder_profile" >}}) - -### Create an origin and set up the Habitat CLI - -1. If you don't already have one, [create an origin]({{< relref "habitat/builder_origins" >}}) in your Chef Habitat Builder account. This origin will store the Habitat package that you create in this tutorial. - -1. If you haven't already done so, run `hab cli setup` and follow the instructions. This will configure the Hab CLI to work with your origin on the Habitat Builder SaaS. - - You will need to provide the origin you created in your Builder account and a personal access token, which you can generate in your [Profile page in Habitat Builder](https://bldr.habitat.sh/#/profile). - -## Fork and Clone the Habitat sample-node-app repository - -1. Create a fork of the [sample-node-app](https://github.com/habitat-sh/sample-node-app) GitHub repository in your own GitHub account. - -1. Clone the fork onto your local workstation. - -## Edit the Plan File - -The [plan file]({{< relref "/habitat/plan_writing" >}}) instructs Chef Habitat in how to build, deploy, and manage your application. - -Edit the plan file to use your origin: - -1. Open the `sample-node-app/habitat/plan.sh` file with your editor of choice. -1. Update the value of `pkg_origin` with the name of the origin in your Habitat Builder account. - -Note the `pkg_deps` setting. This lists dependencies that your package requires at runtime. This Node.js application requires the [`core/node` package](https://bldr.habitat.sh/#/pkgs/core/node/latest), which is maintained by the Habitat Core maintainers. You can see a full list of core packages in the [core-plans](https://github.com/habitat-sh/core-plans) repository, or by searching for **core** in Habitat Builder. - -See the [plan settings]({{< relref "/habitat/plan_settings" >}}) documentation for more information about the settings in a plan file. - -See the [plan writing]({{< relref "/habitat/plan_writing#define-your-dependencies" >}}) documentation for more information defining dependencies. - -## Run the Service in the Habitat Studio - -{{< readfile file="content/habitat/reusable/md/habitat_studio_overview.md" >}} - -Use the Habitat Studio to generate a Habitat package and preview the running Node.js app: - -1. In a terminal, switch to the root of the `sample-node-app` directory. - -1. If you're using Docker, expose port 8000 so you can preview the application in a browser. - - To expose port 8000, run: - - ```bash - export HAB_DOCKER_OPTS="-p 8000:8000" - ``` - -1. Enter the Habitat Studio. - - On macOS run: - - ```bash - hab studio enter - ``` - - On Linux run: - - ```bash - hab studio enter -D - ``` - -1. Now build the package. - - ```bash - build - ``` - - The Studio will generate a package (a `.hart` file) and place it in the `results` directory. - You will also find a `last_build.env` file in the `results` directory that has metadata about the last package build. - -1. Start the service. - - ```bash - hab svc load ORIGIN_NAME/sample-node-app - ``` - -1. Verify that the service is running in the Habitat Studio. - - ```bash - hab svc status - ``` - - This should return a status similar to: - - ```bash - package type desired state elapsed (s) pid group - ORIGIN_NAME/sample-node-app/1.1.0/20221018162840 standalone up up 58 3047 sample-node-app.default - ``` - - Now you can navigate to **localhost:8000** in your browser to see the running service. - -### Shut Down the Service - -1. Stop the service. - - ```bash - hab svc stop ORIGIN_NAME/sample-node-app - ``` - -1. Verify that the service has stopped running. - - ```bash - hab svc status - ``` - -1. And exit the Studio. - - ```bash - exit - ``` - -## Manage the Service with Habitat Builder - -[Chef Habitat Builder]({{< relref "/habitat/builder_overview" >}}) acts as the core of Chef's Application Delivery Enterprise hub. The Chef Habitat Builder SaaS stores plan files where they can be viewed and accessed by the Chef Habitat community and then deployed by the Chef Habitat Supervisor. - -Add your package to your Builder origin and then connect that package to your clone of the sample-node-app repository. Any changes made to your clone of the sample-node-app will trigger the Chef Habitat Builder to rebuild the package. - -1. If you haven't already done so, commit the changes you made earlier to the `plan.sh` file into the default branch of your clone of the sample-node-app repository, and push those changes up to your fork on GitHub. - - The `pkg_origin` setting in the `plan.sh` file should be set to your origin. - -1. Log in to your account in [Chef Habitat Builder](https://bldr.habitat.sh) and select your origin. -1. Create a new package by selecting **Create Package**. - - The name of the package you create must match the package name defined by the `pkg_name` setting in the `plan.sh` file. - -1. Connect the plan file to the new package by selecting **Connect a plan file** and then **for Linux (kernel version 3.2 or later)**. -1. Select your GitHub organization or user account under **Organization**, and then select **sample-node-app** under **Repository**. -1. Select **Save Connection** at the bottom of the page. - -1. Once the plan is connected, select **Latest** towards the top of the page and build the package by selecting **Build latest version** on the right side of the page. - - {{< figure src="/images/habitat/builder-build-latest-version.png" alt="Build latest version button." width=250 >}} - - Select **View the output** and then the **View build job** button ({{< svg file="/static/images/habitat/builder-view-build-job-icon.svg" >}}) to watch the service building in Habitat Builder. - -1. After Habitat Builder finishes building the service, select the **Latest** tab, and then select **Promote** to promote the service to the stable channel. - -## Run the Service From Habitat Builder in the Habitat Studio - -Now that the Node.js app is under management by the Chef Habitat Builder, you can update the service from Habitat Builder. - -1. From a local terminal, enter the Habitat Studio. - - ```bash - hab studio enter - ``` - -1. Verify that a service is not running in the Studio. - - ```bash - hab svc status - ``` - -1. Load the service into the Studio using the at-once update strategy. - - The [at-once update strategy]({{< relref "/habitat/service_group_updates#at-once-strategy" >}}) will pull down the package from Habitat Builder whenever it detects that a new version has been released. - - ```bash - hab svc load ORIGIN_NAME/sample-node-app --strategy at-once - ``` - -1. Now monitor the Habitat Supervisor to watch it update when a new version of the package is created. - - ```bash - sup-log - ``` - - This will show you a streaming log of the Habitat Supervisor output. - -1. Back in the Habitat Builder web UI, rebuild the service by selecting **Build latest version** again. - -1. When Habitat Builder finishes creating a new build of the service, select the **Versions** tab, then select the version of the sample-node-app (1.1.0), and then select **Promote to stable** next to the newest build of the service. - - In your local terminal, the Supervisor log will show your package updating in the Habitat Studio. - - See the [Supervisor Log Codes]({{< relref "/habitat/sup_log_keys" >}}) documentation for an explanation of the different Supervisor log codes. - -## Rebuild the Service From Your GitHub Repository - -From here you can try updating the service by making a change to the sample-node-app repository. - -1. In your local clone of the sample-node-app repository, update the `pkg_version` to `1.2.0` in the `plan.sh` file. - - You might also try updating the message in `habitat/config/config.json` to something like: `Hello friend. This is version {{ pkg.version }} of the Habitat Node.js sample app.` - -1. Commit the change into the default branch of the sample-node-app repository and push the commit up to your fork of sample-node-app. - -1. If your terminal is still running the Supervisor log, continue to the next step. Otherwise, rerun the steps to load the service and view the Supervisor log. - - 1. Expose port 8000. - - ```bash - export HAB_DOCKER_OPTS="-p 8000:8000" - ``` - - 1. Enter the Studio and load the service using the at-once update strategy. - - ```bash - hab studio enter - hab svc load ORIGIN_NAME/sample-node-app --strategy at-once - ``` - - 1. View the Supervisor log. - - ```bash - sup-log - ``` - -1. In [Habitat Builder](https://bldr.habitat.sh/), select **Build latest version** of your package again, then **View the output**, and select the **View build job** button ({{< svg file="/static/images/habitat/builder-view-build-job-icon.svg" >}}). - - {{< note >}} - - If you get an error after selecting **Build latest version**, wait a few minutes and try again. It can take Builder a few minutes to update after changes are made in a GitHub repository. - - {{< /note >}} - -1. After Habitat Builder has finished building the new version of your package, select the **Versions** tab, select the **1.2.0** row, and then select **Promote to stable** and **Yes, promote it**. - - The Supervisor should show a log in your terminal of the package updating to the latest version. After the Supervisor is done updating the service, navigate to **localhost:8000** in your browser and the webpage should show the updated version number and text. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/hab_setup.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/hab_setup.md deleted file mode 100644 index c5f7a40d9b..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/hab_setup.md +++ /dev/null @@ -1,30 +0,0 @@ -+++ -title = "Configure the Chef Habitat CLI" -description = "Set up the Chef Habitat CLI" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Set up the Chef Habitat CLI" - identifier = "habitat/install/hab-setup Install Chef Habitat" - parent = "habitat/install" - weight = 20 -+++ - -Once Chef Habitat has been installed, the `hab` CLI makes it easy to get your workstation configured by guiding through the setup process. To set up your workstation, run `hab cli setup` and follow the instructions. - -screenshot of hab cli setup output in CLI - -Setup asks you to create a new origin and a set of origin keys. - -Optionally, you can also provide a Chef Habitat personal access token to upload packages to the public depot and share them with the Chef Habitat community. See the [access token documentation]({{< relref "builder_profile#create-a-personal-access-token" >}}) for details on generating and using your access token. - -> For more information about using Chef Habitat Builder, see the section on [Using Builder]({{< relref "builder_overview" >}}). - -You will also be asked if you want to register Supervisor control gateway secret (see [Remote Command-and-Control of Supervisors]({{< relref "sup_remote_control" >}}) for further details). - -You can change your settings at any time by re-running the `hab cli setup` command. - -screenshot of completed hab cli setup in CLI - -That's it. You're all set up and ready to use Chef Habitat to build and run packages! diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/install_faq.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/install_faq.md deleted file mode 100644 index 35523ad62a..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/install_faq.md +++ /dev/null @@ -1,42 +0,0 @@ -+++ -title = "Download and Install FAQ" -description = "Download and Install FAQ" -draft = false -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Download and Install FAQ" - identifier = "habitat/install/install-faq Install Frequently Asked Questions FAQ" - parent = "habitat/install" - weight = 30 -+++ - -This section tracks some questions that are frequently encountered when downloading and installing the `hab` binary. - -**Q: Can I just download a GitHub release of Chef Habitat?** - -A: While we do cut releases in GitHub as part of our release process those archives are going to be a `.tar` point in time of our source code. As the `hab` cli is written in Rust, if you follow this approach you'll need to compile the source for your platform. - -**Q: Compile for my platform? Does that mean there aren't any OS native packages of `hab`?** - -A: We publish compiled packages for OSX, Linux, and Windows. `hab` has a requirement of either a Linux kernel >= 2.6.32, OSX >= 10.9, or 64-bit Windows 10 Pro, Enterprise, or Education editions (1511 November update, build 10586 or later) with Hyper-V enabled. - -**Q: What if I need an old version of `hab`?** - -A: We've got you covered! The script we provide for doing curl-bash installations will allow you to specify a `-v` flag to pull down a specific version of Chef Habitat, eg: - -``` -curl https://raw.githubusercontent.com/habitat-sh/habitat/main/components/hab/install.sh \ - | sudo bash -s -- -v 0.56.0 -``` - -**Q: Oh! A curl bash I (love||hate) those.** - -A: Indeed they are divisive, we know, that's why we provide a few different ways for you to download. If you'd like to take a look at the script before running it, you can find it in [the core Chef Habitat repo](https://github.com/habitat-sh/habitat/blob/main/components/hab/install.sh). - -If you're staunchly in the anti-curl-bash camp, you can get the latest packages from the [download links]({{< relref "install_habitat" >}}) listed previously. - -**Q: How do I install `hab` across my server fleet?** - -A: For the most part, we leave that up to you. You could just use the aforementioned curl-bash with your provisioner of choice. If your app was dockerized with Chef Habitat then you won't even need to ask this question, because you'll have everything you need inside your container. We are working on first class Mesosphere DC/OS, and Cloud Foundry integrations - which you can keep up to date on in our [Apache Mesos and DC/OS documentation]({{< relref "mesos_dcos" >}}) and [blog](https://www.chef.io/blog). diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/install_habitat.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/install_habitat.md deleted file mode 100644 index 95892591fe..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/install_habitat.md +++ /dev/null @@ -1,98 +0,0 @@ -+++ -title = "Download and Install the Chef Habitat CLI Tool" -description = "Install the Chef Habitat CLI and configure your workstation for Chef Habitat development" -aliases = ["/habitat/install-habitat/"] -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Get Chef Habitat" - identifier = "habitat/install/installing-packages" - parent = "habitat/install" - weight = 10 -+++ - -Below you'll find installation instructions for each platform and their requirements. The Chef Habitat CLI is currently supported on Linux, Mac, and Windows. - -From building packages to running services, everything in Chef Habitat is done through the hab command-line interface (CLI) tool. To get started using Chef Habitat, you need to download and install the hab CLI tool that corresponds to your workstation OS. -hr - -## Chef Habitat for Linux - -Chef Habitat for Linux requires a 64-bit processor with kernel 2.6.32 or later. On Linux, exporting your Chef Habitat artifact to a Docker image requires the Docker Engine supplied by Docker. Packages from distribution-specific or otherwise alternative providers are currently not supported. - -Once you have downloaded the package, extract the hab binary with tar to `/usr/local/bin` or add its location to your `PATH` (e.g. `tar -xvzf hab.tgz -C /usr/local/bin --strip-components 1`). - -[Download Chef Habitat for Linux](https://www.chef.io/downloads) - -### Install Chef Habitat from the Command Line - -Alternatively, you can install Chef Habitat via the command line by downloading and running the installation script: - -```shell -curl https://raw.githubusercontent.com/habitat-sh/habitat/main/components/hab/install.sh | sudo bash -``` - -### Install Chef Habitat for Linux Kernel 2.x from the Command Line - -Please note that support for Linux Kernel 2.x is limited. Not all core plans are available for Kernel 2.x, nor are there plans to backport all of the existing core plans to Kernel 2.x. Kernel 2.x is legacy technology by definition, and its use should be viewed as a stop-gap to provide interim solutions for old systems, as they are upgraded to more recent versions of the Linux kernel. - -```bash -curl https://raw.githubusercontent.com/habitat-sh/habitat/main/components/hab/install.sh | sudo bash -s -- -t x86_64-linux-kernel2 -``` - -## Chef Habitat for Mac - -Requires 64-bit processor running 10.9 or later - -Once you have downloaded the `hab` CLI, unzip it onto your machine. Unzipping to `/usr/local/bin` should place it on your `PATH`. In order to use the Chef Habitat Studio, you'll also need to install Docker for Mac. - -[Download Chef Habitat for Mac](https://www.chef.io/downloads) - -[Download Docker for Mac](https://store.docker.com/editions/community/docker-ce-desktop-mac) - -### Install Chef Habitat Using Homebrew - -Chef Habitat can also be installed with Homebrew, by running the following commands: - -```bash -brew tap habitat-sh/habitat -brew install hab -``` - -## Chef Habitat for Windows - -Minimum Windows version supported: Windows Server 2012 or Windows 8 64-bit - -Chocolatey is a package manager for Windows. You can use it to easily install, configure, upgrade, and even uninstall Windows software packages. We recommend using Chocolatey for installing Chef Habitat. - -Install Chef Habitat with Chocolatey, by running the following command: - -```powershell -choco install habitat -``` - -### Install Chef Habitat using a Powershell install script - -Alternatively, you can install Chef Habitat by downloading and running the installation script: - -```powershell -Set-ExecutionPolicy Bypass -Scope Process -Force -iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/habitat-sh/habitat/main/components/hab/install.ps1')) -``` - -### Installing Habitat for Windows using the dowloaded Chef Habitat package. - -Downloaded the `hab` CLI, unzip it onto your machine. We suggest unzipping to `C:\habitat`, so that the full path to Chef Habitat is similar to `C:\habitat\hab-0.79.1-20190410221450-x86_64-windows`. If you've downloaded a more recent version of Chef Habitat, you'll see a different set of numbers following `hab-`. Replace the package name used in these examples with the filename you see on your computer. Next, add that folder to your `PATH` variable so your computer will know where to find it. Here's how to do that with Powershell: - -```powershell -$env:PATH += ";C:\habitat\hab-0.79.1-20190410221450-x86_64-windows\" -``` - -To use a Docker Chef Habitat Studio as an isolated environment, you'll also need to install Docker for Windows. - -Docker for Windows requires 64-bit Windows 10 Pro, Enterprise, or Education editions (1607 Anniversary Update, Build 14393 or later) with Hyper-V enabled - -[Download Chef Habitat for Windows](https://www.chef.io/downloads) - -[Download Docker for Windows](https://store.docker.com/editions/community/docker-ce-desktop-windows) diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/keys.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/keys.md deleted file mode 100644 index e9a8799b96..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/keys.md +++ /dev/null @@ -1,49 +0,0 @@ -+++ -title = "Keys" -description = "Chef Habitat Security" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Keys" - identifier = "habitat/reference/keys" - parent = "habitat/reference" - -+++ - -Chef Habitat has strong cryptography built into Chef Habitat Builder, the Supervisor, and the `hab` CLI commands. This means there are several different kinds of keys. - -## Origin Key Pairs - -Every Chef Habitat artifact belongs to an [origin]({{< relref "pkg_ids" >}}) and is cryptographically signed with that origin's private key. Chef Habitat requires the private key for producing artifacts and requires the public key for verification of artifacts before installation. If it is present on Builder, Chef Habitat will automatically download the public key for an origin when necessary. - -Origin key cryptography is asymmetric: it has a public key that you can distribute freely, and a private key that you should keep safe. - -Chef Habitat uses the public origin key to verify the integrity of downloaded artifacts before installing them. -Chef Habitat will only install artifacts for which it has the public origin key. - -You can provide a public origin key to Chef Habitat by pointing it to a Builder site that has the origin key with the `--url` argument to `hab pkg install` or using the `hab origin key import` command. -Use `hab origin key upload` to upload origin keys to Builder. -Use `hab origin key download` to download your origin keys from Builder to your environment. -Use `hab origin key import` to read the key from a standard input stream or local file: - -```bash -hab origin key import -hab origin key import < -curl | hab origin key import -``` - -See the [hab origin key]({{< relref "habitat_cli/#hab-origin-key" >}}) command documentation for more information about working with origin keys from the command line. - -## User and Service Group Keys - -User and service group keys are used to set up trust relationships between these two entities. Service groups can be set up to reject communication (e.g. applying new configuration via `hab config apply`) from untrusted users. - -By default, service groups will trust *any* communication, so for a production deployment of Chef Habitat, setting up these relationships is essential. - -User and service group keys also use asymmetric cryptography. To apply configuration changes to service groups when running in this mode, a user uses their own private key to encrypt configuration information for a service group, using that service group's public key. The service group then uses its private key to decrypt the configuration information, and the user's public key to verify. - -## Ring Encryption Key - -A Supervisor network can be optionally set up to encrypt *all* supervisor-to-supervisor communication. -This requires the use of a symmetric, pre-shared key. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/kubernetes.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/kubernetes.md deleted file mode 100644 index 1bd9925195..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/kubernetes.md +++ /dev/null @@ -1,210 +0,0 @@ -+++ -title = "Kubernetes" -description = "Export your Chef Habitat package as a Docker and run it on a Kubernetes Pod" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Kubernetes" - identifier = "habitat/containers/kubernetes Kubernetes Development Patterns" - parent = "habitat/containers" - weight = 30 -+++ - -[Kubernetes](https://kubernetes.io/) is an open source container cluster manager that is available as a stand-alone platform or embedded in several distributed platforms including [Google's Container Engine](https://cloud.google.com/container-engine/), [AWS Elastic Kubernetes Service](https://aws.amazon.com/eks/), [Azure Kubernetes Service](https://azure.microsoft.com/services/kubernetes-service/), and [Red Hat OpenShift](https://openshift.com/). -Chef Habitat and Kubernetes are complementary. While Kubernetes provides a platform for deployment, scaling, and operations of application containers across clusters of hosts, Chef Habitat manages the build pipeline and lifecycle of those application containers. - -## Chef Habitat on Kubernetes - -Chef Habitat can export your package as a Docker container that runs on Kubernetes in the form of a pod. -Additionally, a Chef Habitat bastion pod provides essential gossip ring features like service discovery (binds), secrets and the required [initial peer]({{< relref "sup_networks" >}}) to all other pods. - -Chef Habitat robustly deploys the bastion pod with a Kubernetes stateful set, persistent volume, and liveness checking, which ensures node availability and ring data persistence. The Kubernetes stateful set comes with an attached Kubernetes service that makes discoverable with DNS. Each namespace should contain a single service and stateful set. - -## Deploy the Chef Habitat Bastion on Kubernetes - -Complete examples may be downloaded from [this folder]({{< relref "pattern_library#kubernetes-bastion-ring-pattern" >}}) - -To explain how this works, let's break down the hab-bastion.yaml file: - -```yaml -apiVersion: v1 -kind: Service -metadata: - name: hab-bastion -spec: - ports: - - name: gossip-listener - protocol: UDP - port: 9638 - targetPort: 9638 - - name: http-gateway - protocol: TCP - port: 9631 - targetPort: 9631 - selector: - app: hab-bastion - clusterIP: None -``` - -This service definition creates a virtual IP (VIP), opening access to the Chef Habitat service that runs on the pod. -- The habitat gossip port (9638/UDP) listener -- The habitat http-gateway (9631/TCP) listener -- makes service name available in DNS (as `hab-bastion` or `hab-bastion.namespace-name`, etc) and discoverable by any pod - -```yaml -apiVersion: apps/v1 -kind: StatefulSet -metadata: - name: hab-bastion -spec: - spec: - securityContext: - fsGroup: 42 -``` - -This section sets the group ownership for the persistent volume mount point so the Habitat Supervisor can write to it. The Habitat user (`hab`) by default has the uid `42` and the gid `42`. - -```yaml - containers: - - name: hab-bastion - image: mydockerorigin/hab_bastion:latest - args: - - '--permanent-peer' -``` - -The `image:` line defines the source of the docker container. In this case, the instructions create an image from a Chef Habitat plan using the `hab pkg export docker` command. It only runs the Chef Habitat Supervisor (hab-sup) service. -The argument `--permanent-peer` instructs the Supervisor to act as a permanent peer. - -```yaml - resources: - requests: - memory: "100Mi" - cpu: "100m" # equivalent to 0.1 of a CPU core -``` - -Resource requests are important because they give instructions to the Kubernetes scheduler--without them, you might overload some nodes while under-using others. - -```yaml - ports: - - name: gossip-listener - protocol: UDP - containerPort: 9638 - - name: http-gateway - protocol: TCP - containerPort: 9631 - readinessProbe: - httpGet: - path: / - port: 9631 - initialDelaySeconds: 5 - periodSeconds: 10 - livenessProbe: - httpGet: - path: / - port: 9631 - initialDelaySeconds: 15 - periodSeconds: 20 -``` - -The `livenessProbe` tells Kubernetes if the pod is healthy or not. If not, the pod gets restarted. -The `readinessProbe` signals to Kubernetes that the pod has started up successfully. - -```yaml - volumeMounts: - - name: hab-bastion - mountPath: /hab/sup - volumeClaimTemplates: - - metadata: - name: hab-bastion - spec: - accessModes: [ "ReadWriteOnce" ] - # uncomment if you don't have a default StorageClass - # storageClassName: "standard" - resources: - requests: - storage: 10Gi -``` - -All of the Habitat Supervisor's state data is stored under `/hab/sup` - we mount this on a persistent volume so it gets re-attached if the pod is ever rescheduled. The data persists! - -## Create a Kubernetes Deployment That Works with the Bastion - -The following is an example of a Kubernetes `Stateful Set` built from the CockroachDB plan. The Bastion pattern uses the `--peer hab-bastion` configuration arguments to instruct the Kubernetes pods to use the `hab-bastion` service as a DNS-resolvable host name. - -```yaml -+++ -apiVersion: apps/v1 -kind: StatefulSet -metadata: - name: cockroachdb -spec: - selector: - matchLabels: - app: cockroachdb - serviceName: cockroachdb - replicas: 3 - template: - metadata: - labels: - app: cockroachdb - spec: - terminationGracePeriodSeconds: 10 - securityContext: - fsGroup: 42 - containers: - - name: cockroachdb - image: irvingpop/cockroach:latest - args: - - --peer - - hab-bastion - - --topology - - leader - resources: - requests: - memory: "300Mi" - cpu: "500m" - ports: - - name: http - containerPort: 8080 - - name: cockroachdb - containerPort: 26257 - volumeMounts: - - name: cockroachdb-data - mountPath: /hab/svc/cockroach/data - volumeClaimTemplates: - - metadata: - name: cockroachdb-data - spec: - accessModes: [ "ReadWriteOnce" ] - resources: - requests: - storage: 10Gi -``` - -## Bare Kubernetes - -If your packages don't require communication with the Chef Habitat Supervisor ring, such as binds, secrets, etc., then you can execute your packages directly on the cluster. You can deploy Chef Habitat packages exported as containers to Kubernetes with the [`kubectl` command](http://kubernetes.io/docs/user-guide/pods/single-container/). Using the [Docker exporter]({{< relref "pkg_exports#exporting-to-docker" >}}) to create a containerized application, you can launch the container like this example: - -```shell -$ kubectl run mytutorial --image=myorigin/mytutorial --port=8080 -``` - -Assuming you're using the Docker image pulled from `myorigin/mytutorial`, port 8080 on the container should be accessible. Pass networking ports exposed by Chef Habitat with `kubectl run` as `--port` options. In this example, the `kubectl get` command is: - -```shell -$ kubectl get pods -l run=mytutorial -``` - -## Docker and ACI - -Chef Habitat packages can be exported in both Docker and ACI formats (as well as others). Kubernetes currently supports the Docker runtime and integration of the rkt container runtime (an implementation of the App Container spec) is under active development. - -## Environment Variables and Networking - -Kubernetes supports passing [environment variables](https://kubernetes.io/docs/user-guide/environment-guide/) into containers. - -## Related Reading - -* [Export a Chef Habitat package]({{< relref "pkg_exports" >}}) -* [Chef Habitat CLI]({{< relref "habitat_cli" >}}) diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/mesos_dcos.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/mesos_dcos.md deleted file mode 100644 index 92cce4ebbc..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/mesos_dcos.md +++ /dev/null @@ -1,88 +0,0 @@ -+++ -title = "Apache Mesos and DC/OS" -description = "Apache Mesos and DC/OS" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Apache Mesos and DC/OS" - identifier = "habitat/containers/mesos-dcos" - parent = "habitat/containers" - weight = 70 -+++ - -[Apache Mesos](https://mesos.apache.org/) is an open source distributed systems kernel and the distributed systems kernel for [Mesosphere's DC/OS](https://dcos.io) distributed platform. - -## Mesos Containerizers - -Mesos has support for [containerizers](https://mesos.apache.org/documentation/latest/containerizers/) for running commands and applications within isolated containers. Mesos supports Docker and its own [Mesos containerizer](https://mesos.apache.org/documentation/latest/mesos-containerizer/) format. The Mesos containerizer provides lightweight containerization with `cgroups/namespaces` isolation without actual isolation. The `hab pkg export mesos` command creates a mostly empty base filesystem with the application and the Chef Habitat Supervisor and packages it into a compressed tarball. - -## Marathon Applications - -[Marathon](https://mesosphere.github.io/marathon/) is a container orchestration platform for Mesos and DC/OS, handling the scheduling and deployment of applications. [Marathon applications](https://mesosphere.github.io/marathon/docs/application-basics.html) support Docker and the Mesos container formats, wrapping them in JSON metadata describing the resources needed to deploy the application. Once the application has been deployed to Marathon, it schedules it across the Mesos cluster and ensures the application is running optimally. - -### Export to a Mesos Container and Marathon Application - -You can create native Mesos containers from Chef Habitat packages by following these steps: - -1. Create an interactive studio in any directory with the `hab studio enter` command. - -2. Install or [build]({{< relref "pkg_build" >}}) the Chef Habitat package from which you want to create a Marathon application, for example: - - ```bash - $ hab pkg install yourorigin/yourpackage - ``` - -3. Run the Mesos exporter on the package. - - ```bash - $ hab pkg export mesos yourorigin/yourpackage - ``` - -4. This will create a Mesos container-format tarball in the results directory, and also print the JSON needed to load the application into Marathon. Note that the tarball needs to be uploaded to a download location and the `"uris"` in the JSON need to be updated manually. This is an example of the output: - - ```json - { - "id": "yourorigin/yourpackage", - "cmd": "/bin/id -u hab &>/dev/null || /sbin/useradd hab; /bin/chown -R hab:hab *; mount -t proc proc proc/; mount -t sysfs sys sys/;mount -o bind /dev dev/; /usr/sbin/chroot . ./init.sh start yourorigin/yourpackage", - "cpus": 0.5, - "disk": 0, - "mem": 256, - "instances": 1, - "uris": [ "https://storage.googleapis.com/mesos-habitat/yourorigin/yourpackage-0.0.1-20160611121519.tgz" ] - } - ``` - -5. Note that the default resource allocation for the application is very small: 0.5 units of CPU, no disk, one instance, and 256MB of memory. To change these resource allocations, pass different values to the Mesos exporter as command line options (defaults are documented with `--help`). - -6. From the DC/OS web interface, launch the Marathon Service. - - ![Screen shot of DC/OS Services](/images/habitat/mesos1-services-marathon.png) - -7. Select "Create Application". - - ![Screen shot of Marathon Applications List](/images/habitat/mesos2-new-application.png) - -8. Click on the "JSON Mode" selector and enter the JSON output of the Mesos exporter and click "Create Application". - - ![Screen shot of Marathon New Application JSON Mode](/images/habitat/mesos3-new-application-json.png) - -9. Marathon will then deploy the application and enter the "Running" status. - - ![Screen shot of Marathon Application Running](/images/habitat/mesos4-application.png) - -## Debugging - -You can get to the output from the running application by clicking on the "Marathon" service from the DC/OS "Services" tab. Select the application and the "Log Viewer" and choose either the "Error" or "Output" to see `stderr` and `stdout` respectively. If you have SSH access into the nodes, the Mesos container directories are beneath `/var/lib/mesos/slave/slaves`. - ![Screen shot of Debugging a Running Application](/images/habitat/mesos5-debugging.png) - -## Future Enhancements - -This is a basic integration, there are many improvements yet to be made. Here are a few examples: - - * Marathon environment variables are not passed into the Chef Habitat package "cmd" yet. - * Networking ports exposed by Chef Habitat need to be added to the JSON. - * The Chef Habitat gossip protocol needs to be included as a default exposed port. - * If Marathon is running the [artifact store](https://mesosphere.github.io/marathon/docs/), support uploading the tarball directly into it. - * Upload applications directly to the [Marathon application API](https://mesosphere.github.io/marathon/docs/application-basics.html). - * Marathon supports unpacking several archive formats. Native `.hart` support could be added directly to Marathon. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/monitor_services.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/monitor_services.md deleted file mode 100644 index 80f7032b66..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/monitor_services.md +++ /dev/null @@ -1,112 +0,0 @@ -+++ -title = "Monitoring Services" -description = "Monitoring Services" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Monitoring Services" - identifier = "habitat/services/service-monitor" - parent = "habitat/services" - weight = 70 -+++ - -Use the HTTP API to monitor services. When a service starts, the [Supervisor]({{< relref "sup_networks">}}) exposes the status of its services' health and other information through an HTTP API endpoint. This information can be useful in monitoring service health, results of leader elections, and so on. - -## Authentication - -The Supervisor currently supports simple HTTP authentication using Bearer tokens. -By default, no authentication is used. If you would like to require authentication, -export the `HAB_SUP_GATEWAY_AUTH_TOKEN` environment variable before starting the -Supervisor. All HTTP requests will then require that same token to be present in -an Authorization header, or they will receive a 401 Unauthorized response. - -## Endpoints - -The HTTP API provides information on the following endpoints: - -* `/butterfly` - Debug information about the rumors stored via Butterfly. -* `/census` - Returns the current Census of Services on the Ring (roughly what you see as a service in config.toml). -* `/services` - Returns an array of all the services running under this Supervisor. -* `/services/{name}/{group}` - Returns the information of a single loaded service. -* `/services/{name}/{group}/config` - Returns this service group's current configuration. -* `/services/{name}/{group}/health` - Returns the current health check for this service. -* `/services/{name}/{group}/{organization}` - Returns information of a single loaded service scoped to an organization -* `/services/{name}/{group}/{organization}/config` - Returns the service group's current configuration, but includes the organization. -* `/services/{name}/{group}/{organization}/health` - Same as above, but includes the organization. - -### Errors - -Most of the HTTP API endpoint return these errors: - -| Error | Description | -| ----- | ----------- | -| 404 | Service not loaded | -| 503 | Supervisor hasn't fully started. Try again later. | - -The `/health` endpoints return: - -| Error | Description | -| ----- | ----------- | -| 404 | Service not loaded | -| 500 | Health Check - Unknown | -| 503 | Health Check - Critical | - -## Usage - -Connect to the Supervisor of the running service using the following syntax. This example uses `curl` to do the GET request. - -```bash -curl http://172.17.0.2:9631/services -``` - -**Note**: The default listening port on the Supervisor is 9631; however, you can change the listening port by using the `--listen-http` option when starting a service. - -Depending on the endpoint you hit, the data may be formatted in JSON, TOML, or plain text. - -### Example - -```bash -$ HAB_SUP_GATEWAY_AUTH_TOKEN="sekret" hab sup run -hab-sup(MR): Supervisor Member-ID e89b6616d2c040c8a82f475b00ba8c69 -hab-sup(MR): Starting gossip-listener on 0.0.0.0:9638 -hab-sup(MR): Starting ctl-gateway on 0.0.0.0:9632 -hab-sup(MR): Starting http-gateway on 0.0.0.0:9631 -``` - -```bash -$ curl -v http://172.17.0.2:9631/services -* Trying 172.17.0.2... -* TCP_NODELAY set -* Connected to 172.17.0.2 (172.17.0.2) port 9631 (#0) -> GET /services HTTP/1.1 -> Host: 172.17.0.2:9631 -> User-Agent: curl/7.54.0 -> Accept: */* -> -< HTTP/1.1 401 Unauthorized -< content-length: 0 -< date: Thu, 15 Nov 2018 22:39:41 GMT -< -* Connection #0 to host 172.17.0.2 left intact -``` - -```bash -$ curl -v -H "Authorization: Bearer sekret" http://172.17.0.2:9631/services -* Trying 172.17.0.2... -* TCP_NODELAY set -* Connected to 172.17.0.2 (172.17.0.2) port 9631 (#0) -> GET /services HTTP/1.1 -> Host: 172.17.0.2:9631 -> User-Agent: curl/7.54.0 -> Accept: */* -> Authorization: Bearer sekret -> -< HTTP/1.1 200 OK -< content-length: 2 -< content-type: application/json -< date: Thu, 15 Nov 2018 22:41:42 GMT -< -* Connection #0 to host 172.17.0.2 left intact -[] -``` diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/on_prem_flow.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/on_prem_flow.md deleted file mode 100644 index 0ad13da3fa..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/on_prem_flow.md +++ /dev/null @@ -1,16 +0,0 @@ -+++ -title = "Chef Habitat Builder on-prem Flow" -description = "Chef Habitat Builder on-prem Flow" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Chef Habitat Builder on-prem Flow" - identifier = "habitat/diagrams/on-prem-flow" - parent = "habitat/diagrams" - weight = 100 - -+++ - -![Chef Habitat On-premises Builder Depot Flow Diagram](/images/habitat/habitat-on-premises-builder-depot-flow.png) - diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/origin_keys.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/origin_keys.md deleted file mode 100644 index 2ac10b84bb..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/origin_keys.md +++ /dev/null @@ -1,189 +0,0 @@ -+++ -title = "Origin Keys" - -date = 2020-10-12T13:59:46-07:00 -draft = false -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Origin Keys" - identifier = "habitat/origins/origin-keys Origin Keys" - parent = "habitat/origins" - weight = 20 -+++ - -Prerequisites: - -- [Get Chef Habitat]({{< relref "install_habitat.md" >}}) -- [Create a Chef Habitat Builder account]({{< relref "builder_account#builder-account" >}}) -- [Generate a personal access token]({{< relref "builder_profile#create-a-personal-access-token" >}}) -- [Create an origin]({{< relref "origins" >}}) or join an origin by [invitation]({{< relref "origin_rbac#manage-origin-membership-with-hab-origin-invitations" >}}) - -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 (also called a "signing key") that you should distribute only to users of the origin. -All Chef Habitat Builder users with access to the origin can view the public origin key revisions in the origin key tab (Builder > Origin > Keys) and download the public origin key, but only users with the origin 'administrator' or 'owner' roles can view or download the private origin 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 the private origin key -- When you upload an artifact to Chef Habitat Builder or Builder on-prem, Chef Habitat uses the public origin key to verify that the artifact was signed with the private origin key -- When you install any package onto a Chef Habitat Supervisor, Chef Habitat uses the public origin key to verify the package's integrity before it starts the installation -- When you download an artifact to your local Chef Habitat Studio, 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" - -## The Keys Tab - -When you create an origin, Chef Habitat Builder automatically generates an origin key pair and saves both keys. To view your origin keys on Chef Habitat Builder, navigate to your origin and select the **Keys** tab. (Builder > Origins > Keys) You will always be able to view and download public origin 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 from the Keys Tab - -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 from the Keys Tab - -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.md/#hab-origin-key" >}}) commands. - -### Find Your 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 Origin Keys in a Local Environment - -On Windows: - -```PowerShell -Get-ChildItem C:\hab\cache\keys -``` - -On Linux or macOS: - -```bash -ls -la ~/.hab/cache/keys -``` - -#### Find Origin Keys in 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 - -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.md" >}}) to generate your first origin key pair as part of setting up the `hab` CLI -- Use the `hab origin key generate ` command to create a key pair for an origin - -Create origin keys with the `hab` command: - -```hab -hab origin key generate -``` - -### Download Origin Keys - -To get your public origin key using the command line, use: - -```hab -hab origin key download -``` - -### Upload Origin Keys - -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 private origin 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 - -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 -cat | 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 -``` diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/origin_rbac.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/origin_rbac.md deleted file mode 100644 index 5402cfe56d..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/origin_rbac.md +++ /dev/null @@ -1,169 +0,0 @@ -+++ -title = "Origin Membership & RBAC" -date = 2020-10-12T13:53:50-07:00 -draft = false -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Origin Membership & RBAC" - identifier = "habitat/origins/origin-rbac Builder RBAC" - parent = "habitat/origins" - weight = 30 -+++ - -Prerequisites: - -- [Download the Chef Habitat CLI]({{< relref "install_habitat.md" >}}) -- [Create a Chef Habitat Builder account]({{< relref "builder_account" >}}) -- [Generate a personal access token]({{< relref "builder_profile#create-a-personal-access-token" >}}) -- [Create an origin]({{< relref "origins.md#create-origin" >}}) or accept an [invitation]({{< relref "#manage-origin-membership-with-hab-origin-invitations" >}}) to an existing origin -- [Get origin keys]({{< relref "origins.md#origin-keys" >}}) - -## Role-Based Access Control (RBAC) for Chef Habitat Builder (SaaS and on-prem) - -Role-Based Access Control (RBAC) membership is a token-based authentication process that works at the origin level. RBAC improves operational safety by letting you enable specific levels of access to each user of an origin. The membership role defines the level of access to resources within an origin. When you first join or create an origin, Chef Habitat Builder identifies your personal access token and assigns a membership role to it for that origin. By default, when you join an origin you're assigned the "read-only" role and when you create an an origin you're assigned the 'owner' role. Role access is cumulative and progressive--each RBAC role includes all of the privileges of the previous roles and adds new access privileges. - -RBAC Origin Member Roles: - -Read-Only -: The default membership role for any user joining an origin. 'Read-Only' users can read an origin's packages, channels, origin membership, jobs, keys, integrations, invitations, roles, and settings. 'Read-Only' users cannot add to, change, or delete anything in the origin, including uploading packages and inviting users to 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 -: In addition to 'Member' access, 'Maintainers' can write to packages, origin membership, jobs, integrations, invitations, and promote packages from 'unstable' to other channels. Maintainers can read origin keys and settings, but cannot add, update or delete them. 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. 'Maintainers' can neither read nor write origin secrets. - -Administrator -: In addition to 'Maintainer' access, the 'Administrator' role has write access to origin keys and can add, update, and delete origin membership. An 'Administrator' can read and write origin secrets. - -Owner -: The origin 'Owner' has full read and write access to all aspects of the origin. Only Owners can delete the origin or transfer ownership to another member. - -## Comparison of RBAC Membership 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 - -The `hab` CLI supports RBAC. You need to use the CLI to manage origin roles, you cannot manage origin roles from the Chef Habitat Builder site. - -![Manage origin membership](/images/habitat/origin-members.png) - -### Manage origin membership with `hab origin invitations` - -Use the [hab origin invitations]({{< relref "habitat_cli.md#hab-origin-invitations" >}}) command to invite users to join your origin and to respond to invitations. Origin Administrators and Owners can use this command to manage invitations. - -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 origin rbac` - -Use the [hab origin rbac]({{< relref "habitat_cli.md#hab-origin-rbac" >}}) command to see and set 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: - -```bash -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 -``` diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/origin_settings.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/origin_settings.md deleted file mode 100644 index 845e165e80..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/origin_settings.md +++ /dev/null @@ -1,103 +0,0 @@ -+++ -title = "Origin Settings" -date = 2020-10-12T14:02:01-07:00 -draft = false -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Origin Settings" - identifier = "habitat/origins/origin-settings Origin Settings" - parent = "habitat/origins" - weight = 40 -+++ - -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 an origin by switching from **Public Packages** to **Private Packages**. The default setting is required for each origin. Packages can have different default visibility settings than the origin to which they belong. You can change the default visibility setting in for an individual packages in the package 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. - -Only Chef Habitat Builder can read encrypted origin secrets. The origin secrets in your local environment are encrypted with an origin encryption key. Origin secrets are retained by the origin and are available for any of its packages. - -### 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.md#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. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/origins.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/origins.md deleted file mode 100644 index 752f458df9..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/origins.md +++ /dev/null @@ -1,37 +0,0 @@ -+++ -title = "Overview of Chef Habitat Builder origins" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Overview" - identifier = "habitat/origins/overview" - parent = "habitat/origins" - weight = 10 -+++ - -{{< readfile file="/habitat/reusable/md/builder_origins.md" >}} - -## 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 on-prem Habitat Builder deployment. - -## 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]({{< relref "/habitat/origin_keys/#generate-origin-keys" >}}) documentation. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/package_build_flow.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/package_build_flow.md deleted file mode 100644 index 242b90e85a..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/package_build_flow.md +++ /dev/null @@ -1,15 +0,0 @@ -+++ -title = "Initial Package Build Flow" -description = "Initial Package Build Flow" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Initial Package Build Flow" - identifier = "habitat/diagrams/package-build-flow" - parent = "habitat/diagrams" - weight = 20 -+++ - -![Chef Habitat Initial Package Build Flow Diagram](/images/habitat/habitat-initial-package-build-flow.png) - diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/package_contents.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/package_contents.md deleted file mode 100644 index e6dbef9ffa..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/package_contents.md +++ /dev/null @@ -1,89 +0,0 @@ -+++ -title = "Package Contents" -description = "Package Contents" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Package Contents" - identifier = "habitat/reference/package-contents" - parent = "habitat/reference" -+++ - -During the build process, the hab-plan-build script creates several files that specify dependency, build, and configuration information. When packages are unpacked (extracted) and installed during the initialization phase of a Chef Habitat service, these files define what those packages need to run. - -Packages are installed in the `/hab/pkgs/` directory, and then further organized in subdirectories corresponding to fully-qualified package identifiers: `origin/name/version/release`. For more information on package identifiers, see [Packages]({{< relref "pkg_ids" >}}). - -## Contents of a Chef Habitat package - -BUILD_DEPS -: Fully-qualified package identifiers of any build dependencies that your package depends on. These are listed in the root plan.sh file of your plan directory. - -BUILD_TDEPS -: Fully-qualified package identifiers of any runtime dependencies that the build dependencies for your project depend on. This is essentially a flattened tree of dependencies all the way up to the root dependency (`linux-headers` in most cases). - -BUILDTIME_ENVIRONMENT -: A file that contains similar information as the RUNTIME_ENVIRONMENT file, but is constructed from a package's build-time dependencies instead of its runtime dependencies. This file is not currently consumed by any other software in the Chef Habitat ecosystem, but can be used for troubleshooting and informative purposes. - -BUILDTIME_ENVIRONMENT_PROVENANCE -: A file that provides information on which specific dependencies have influenced the final value of a given variable in the BUILDTIME_ENVIRONMENT file. This file is not currently consumed by any other software in the Chef Habitat ecosystem, but can be used for troubleshooting and informative purposes. - -CFLAGS -: Additional switches to be passed to the compiler when this package is used as a build dependency. - -DEPS -: Runtime dependencies for your package. These dependencies are processed by Chef Habitat and their corresponding environment variables (such as `PATH` and `LD_LIBRARY_PATH`) are added to the current environment. - -FILES -: List of all files in this package along with their blake2b checksums. The FILES file itself is signed using `hab pkg sign` to provide an assurance that its contents haven't been tampered with. - -IDENT -: The fully-qualified identifier for the package. The format is `origin/name/version/release`. - -INTERPRETERS -: If `pkg_interpreters` is specified in your plan.sh, then this file will be generated and contain a list of absolute paths to any interpreters that a package can provide. Code in a `plan.sh` may use the `fix_interpreter` function to replace hard-coded instances of interpreters, such as `/bin/env`. The location of interpreters in Chef Habitat will be nested under `/hab/pkgs/`. For more information on interpreters, see the fix_interpreter description in [Plan helper functions]({{< relref "build_helpers" >}}). - -LDFLAGS -: Additional switches to be passed to the compiler when this package is used as a build dependency. - -LD_RUN_PATH -: Additional switches to be passed to the compiler when this package is used as a build dependency. - -MANIFEST -: A file containing package information, such as checksum, maintainer, build variables, and other metadata specified in plan.sh as well as the contents of the plan.sh itself. - -PATH -: A file that contains all directories in the package which contain program binaries. The directories are separated with the target platform's path separator character (i.e. either `:` or `;`). - -RUNTIME_ENVIRONMENT -: A file containing the result of the layering operation of the current package's runtime environment variables on top of those of its dependencies. This is what the build process consults when it processes dependencies, and this is what the Supervisor consults in concert with `RUNTIME_PATH` when generating the full set of environment variables that should be added to an environment before running a supervised process. - -RUNTIME_ENVIRONMENT_PROVENANCE -: A file that provides information on which specific dependencies have influenced the final value of a given variable in the RUNTIME_ENVIRONMENT file. This file is not currently consumed by any other software in the Chef Habitat ecosystem, but can be used for troubleshooting and informative purposes. - -RUNTIME_PATH -: A file that contains all directories that need to be prepended to an environment's `$PATH` before a program in this package can be expected to run correctly. The order of the elements are precise and meaningful so should not be altered. This file is used in concert with `RUNTIME_ENVIRONMENT` to compute the full set of environment variables that should be added to an environment before running a program in this package. - -TARGET -: The CPU architecture and platform for the package. The format is `architecture-platform`. For example, x86_64-linux. - -TDEPS -: Fully-qualified package identifiers of any runtime dependencies that the runtime dependencies for your project depend on. This is essentially a flattened tree of dependencies all the way up to the root dependency (`linux-headers` in most cases). - -SVC_GROUP -: The value of `pkg_svc_group` from a plan. The Chef Habitat Supervisor will try to start a service with this group if it exists. - -SVC_USER -: The value of `pkg_svc_user` from a plan. The Chef Habitat Supervisor will try to start a service with this user if it exists. - -default.toml -: If you have defined a `default.toml` file in the root of your plan, then it will be included in the same relative location within the installed package directory. For more information on configuration and the default.toml file, see [Configuration Updates]({{< relref "service_updates" >}}). - -config directory -: If you have defined a `config` subdirectory with a templatized configuration file in your plan, then they will be included in the same relative location within the installed package directory. For more information on templatized configuration files, see [Add configuration to plans]({{< relref "config_templates" >}}). - -config_install directory -: If you have defined a `config_install` subdirectory with a templatized configuration file in your plan, then they will be included in the same relative location within the installed package directory. For more information on templatized configuration files, see [Add configuration to plans]({{< relref "config_templates" >}}). - -hooks directory -: If you have defined a `hooks` subdirectory with hook scripts in your plan, then they will be included in the same relative location within the installed package directory. Read more about [Application Lifecycle Hooks]({{< relref "application_lifecycle_hooks" >}}). diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/pattern_library.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/pattern_library.md deleted file mode 100644 index d59da2351d..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/pattern_library.md +++ /dev/null @@ -1,285 +0,0 @@ -+++ -title = "Pattern Library Introduction" -description = "Example code for Chef Habitat plans and more!" -gh_repo = "habitat" -aliases = ["/habitat/pattern-library/"] - -[menu] - [menu.habitat] - title = "Pattern Library" - identifier = "habitat/pattern_library" - parent = "habitat/reference" -+++ -## Chef Habitat Pattern Library - -The Chef Habitat Pattern Library is an evolving set of design patterns to use as starting-points. These patterns are examples and require configuration and customization for your unique situation. - -For help with Chef Habitat and these patterns, ask: - -- Your customer support agent -- In the [Chef Discourse](https://discourse.chef.io/c/habitat/) - -## Kubernetes Bastion Ring Pattern - -A _bastion ring_ is a robust type of Supervisor network in which a small number of Supervisors are set up as permanent peers and that are dedicated to anchoring Supervisor network communication. These Supervisors are designated solely for communication between Supervisor and _do not run services_. These solely to anchor the entire Supervisor network. See [Supervisor Networks]({{< relref "sup_networks" >}}) for more information. The following examples demonstrate running a bastion ring in Kubernetes. - -### Kubernetes Bastion Ring Plan - -```bash -pkg_name=hab_bastion -pkg_origin=habitat -pkg_version="0.1.0" -pkg_maintainer="irvingpop" -pkg_license=("Apache-2.0") -pkg_deps=(core/busybox-static) -pkg_svc_run="while true; do sleep 60; done" - -do_build() { - return 0 -} - -do_install() { - return 0 -} -``` - -### Kubernetes Bastion Ring Producer Pattern - -```yaml ---- -apiVersion: v1 -kind: Service -metadata: - name: hab-bastion -spec: - ports: - - name: gossip-listener - protocol: UDP - port: 9638 - targetPort: 9638 - - name: http-gateway - protocol: TCP - port: 9631 - targetPort: 9631 - selector: - app: hab-bastion - clusterIP: None - ---- -apiVersion: apps/v1 -kind: StatefulSet -metadata: - name: hab-bastion -spec: - selector: - matchLabels: - app: hab-bastion - serviceName: hab-bastion - replicas: 1 - template: - metadata: - labels: - app: hab-bastion - spec: - terminationGracePeriodSeconds: 10 - securityContext: - fsGroup: 42 - containers: - - name: hab-bastion - image: irvingpop/hab_bastion:latest - args: - - '--permanent-peer' - resources: - requests: - memory: "100Mi" - cpu: "100m" # equivalent to 0.1 of a CPU core - ports: - - name: gossip-listener - protocol: UDP - containerPort: 9638 - - name: http-gateway - protocol: TCP - containerPort: 9631 - readinessProbe: - httpGet: - path: / - port: 9631 - initialDelaySeconds: 5 - periodSeconds: 10 - livenessProbe: - httpGet: - path: / - port: 9631 - initialDelaySeconds: 15 - periodSeconds: 20 - volumeMounts: - - name: hab-bastion - mountPath: /hab/sup - volumeClaimTemplates: - - metadata: - name: hab-bastion - spec: - accessModes: [ "ReadWriteOnce" ] - # uncomment if you don't have a default storageclass - # storageClassName: "standard" - resources: - requests: - storage: 10Gi -``` - -### Kubernetes Bastion Ring Consumer Pattern - -```yaml - apiVersion: apps/v1 -kind: StatefulSet -metadata: - name: cockroachdb -spec: - selector: - matchLabels: - app: cockroachdb - serviceName: cockroachdb - replicas: 3 - template: - metadata: - labels: - app: cockroachdb - spec: - terminationGracePeriodSeconds: 10 - securityContext: - fsGroup: 42 - containers: - - name: cockroachdb - image: irvingpop/cockroach:latest - args: - - --peer - - hab-bastion - - --topology - - leader -# env: -# - name: HAB_COCKROACH -# value: | - resources: - requests: - memory: "300Mi" - cpu: "500m" # equivalent to 0.5 CPU core - ports: - - name: http - containerPort: 8080 - - name: cockroachdb - containerPort: 26257 - volumeMounts: - - name: cockroachdb-data - mountPath: /hab/svc/cockroach/data - volumeClaimTemplates: - - metadata: - name: cockroachdb-data - spec: - accessModes: [ "ReadWriteOnce" ] - resources: - requests: - storage: 10Gi -``` - -## hab pkg download Patterns - -The `hab pkg download` command can be used to download individual -packages (along with their dependencies and keys) from Builder, -without installing them. This allows you to more easily transfer -packages from one Builder instance to another, or to take a selective -snapshot of particular packages. - -While you can download packages one-at-a-time, it can be more -convenient to use a file to specify your packages. Two formats are -recognized: plain text and TOML. - -### Plain Text Download Descriptors - -The simplest thing you can do is create a plain text file with a -package identifier on each line, like so: - -```text -# These are the packages needed to run a Supervisor -core/hab-launcher -core/hab -core/hab-sup -``` - -Each line is a valid package identifier. You can also add comments using `#`. - -To download these packages (and their dependencies), save that to a file named `supervisor.txt` and run: - -```bash -hab pkg download --file=supervisor.txt -``` - -This will download the packages into your existing Habitat cache directory. -Alternatively, you can specify a directory using the `--download-directory` option. - -(You can also specify `--channel` and `--target` to further control which specific packages you download; run `hab pkg download --help` for more). - -### TOML Download Descriptors - -Plain text is fine for simple cases, but has drawbacks. -For instance, all packages will come from the same channel and will be for the same platform target. -For maximum flexibility, you'll want to use TOML to -write your download descriptor. Here is an example of one that the Habitat core team uses to take periodic snapshots of everything needed to run Builder itself: - -```toml -format_version = 1 -file_descriptor = "Packages needed to run an instance of Builder" - -[[x86_64-linux]] -channel = "stable" -packages = [ - # Supervisor and prerequisites - "core/hab-launcher", - "core/hab", - "core/hab-sup", - - # Utilities - "core/sumologic", - "core/nmap" -] - -# Targets can be repeated to specify additional subsets of packages, -# possibly from different channels -[[x86_64-linux]] -channel = "stable" -packages = [ - # Builder services - "habitat/builder-api", - "habitat/builder-api-proxy", - "habitat/builder-jobsrv", - "habitat/builder-worker", - "habitat/builder-memcached", -] - -[[x86_64-linux-kernel2]] -channel = "stable" -packages = [ - # Supervisor and prerequisites - "core/hab-launcher", - "core/hab", - "core/hab-sup", - - "habitat/builder-worker" -] - -[[x86_64-windows]] -channel = "stable" -packages = [ - # Supervisor and prerequisites - "core/windows-service", - "core/hab", - "core/hab-sup", - - "habitat/builder-worker" -] -``` - -This format allows us to specify multiple subsets of packages from different channels and for different architectures. -Here, we are pulling down all the core service packages, which run on Linux, but are also pulling down the platform-specific versions of the -`habitat/builder-worker` package. -Without this format, we would have to invoke `hab pkg download` multiple times with different parameters. -The file allows us to capture our full intention in one place. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/pkg_binds.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/pkg_binds.md deleted file mode 100644 index 218a4936c5..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/pkg_binds.md +++ /dev/null @@ -1,119 +0,0 @@ -+++ -title = "Runtime Binds" -description = "Define runtime binds in your plan file" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Runtime Binds" - identifier = "habitat/packages/pkg-binds" - parent = "habitat/packages" - -+++ -*Runtime binding* in Chef Habitat refers to the ability for one service group to connect to another, forming a producer-consumer relationship where the consumer service can use the producer service's current configuration in order to configure itself at runtime. When the producer's configuration change, the consumer is notified and can reconfigure itself as needed. - -With runtime binding, a consumer service can use a "binding name" of their choosing in their configuration and lifecycle hook templates as a kind of handle to refer to the configuration values they need from the producer service. This name isn't inherently tied to any particular package or service group name. Instead, when the service is run, users associate a service group with that binding name, which gives Chef Habitat all the information it needs to wire the producer and consumer services together. - -Let's look at how we set up this relationship in detail. - -### Defining the Producer Contract - -A producer service defines its contract by "exporting" a subset of its runtime configuration. This is done by defining values in the `pkg_exports` associative array defined in your package's `plan.sh`. For example, a database server named `amnesia` might define the following exports: - -```bash -pkg_exports=( - [port]=network.port - [ssl-port]=network.ssl.port -) -``` - -Note that Powershell plans use hashtables where Bash plans use associative arrays. A `plan.ps1` would declare its exports as: - -```powershell -$pkg_exports=@{ - port="network.port" - ssl-port="network.ssl.port" -} -``` - -This will export the runtime values of its `network.port` and `network.ssl.port` configuration entries publicly as `port` and `ssl-port`, respectively. All configuration entries in `pkg_exports` must have a default value in `default.toml`, but the actual exported values will change at runtime to reflect the producer's current configuration. When values change (for example, by `hab config apply`), the consumer service will be notified that its producer service configuration has changed. We'll see how to use this on the consumer in the sections below. - -Producer services export only the *subset* of their configuration that is defined through `pkg_exports` and not the entire thing. Consumer services see only what the producer service exports, and nothing more. This is important, because it means that configuration that must remain secret--such as passwords--are not shared _unless_ they are explicitly defined in `pkg_exports`. - -Additionally, the internal structure of the producer's configuration is independent of the exported interface it presents. In our example, `ssl-port` originally comes from a deeply-nested `network.ssl.port` value. However, the exported interface is _flat_, effectively a non-nested set of key-value pairs. - -### Defining the Consumer Contract - -The consumer service defines a "binding name" as a handle to refer to a service group from which it receives configuration data. However, it must do more than just name the bind, it must also state the configuration values it expects from the service group. Chef Habitat will make sure that whatever service group is bound actually exports the expected values to the consumer service. - -As an example, let's say we have an application server, called `session-server`, that needs to connect to a database service, and needs both a "port" and an "ssl-port" in order to make that connection. We can describe this relationship in our `plan.sh` file like so: - -```bash -pkg_binds=( - [database]="port ssl-port" -) -``` - -Here, `pkg_binds` is an associative array. The key ("database") is the binding name, while the value ("port ssl-port") is a space-delimited list of the exported configuration the binding requires. A consumer can specify multiple binds; each would be an individual entry in this associative array. Judging from this, the producer we described above would be a good candidate for this application server to bind to, because it exports both a "port" and an "ssl-port". - -A bound service group may export additional values, but they cannot export less and still satisfy the contract. - -Chef Habitat only matches services up at the syntactic, not semantic, level of this contract. If you bind to a service that exports a "port", Chef Habitat only knows that the service exports something called "port"; it could be the port for a PostgreSQL database, or it could be the port of an application server. You will need to ensure that you connect the correct services together; Chef Habitat's binds provide the means by which you express these relationships. You are, however, free to create bind names and export names that are meaningful for you. - -#### The Difference Between _pkg\_binds_ and _pkg\_binds\_optional_ - -In addition to the `pkg_binds` array, Plan authors may also specify `pkg_binds_optional`. It has exactly the same structure as `pkg_binds`, but, as the name implies, these bindings are _optional_; however, it is worth examining exactly what is meant by "optional" in this case. - -In order to load a service into the Supervisor, each bind defined in `pkg_binds` *must* be mapped to a service group; if any of these binds are not mapped, then the Supervisor will refuse to load the service. - -Binds defined in `pkg_binds_optional`, on the other hand, *may* be mapped when loading a service. If a service group mapping is not defined at load time, the Supervisor will load the service without question. As an extreme example, a service could have no `pkg_binds` entries, and five `pkg_binds_optional` entries; such a service could be loaded with no binds mapped, one bind mapped, all the way to mapping all five binds. - -There are several scenarios where optional binds may be useful: - - * A service may have some default functionality which may be overridden at load-time by mapping an optional binding. Perhaps you have some kind of artifact repository service that, in the absence of a "remote-store" bind stores data on the local filesystem. However, if `remote-store` is bound to an appropriate S3 API-compatible service, such as [Minio](https://www.minio.io), it could modify its behavior to store data remotely. - - * A service can be optionally bind to a service to unlock additional features. For example, say you have an application that may run with or without a caching layer. You can model this using an optional bind named (say), "cache". If you wish to run without the caching functionality enabled, you can start the service without specifying a service group mapping for the "cache" bind. Since the bind is optional, it is not needed for Chef Habitat to run your service. However, if you do wish to run with the caching enabled, you can specify a service group mapping, e.g. `hab svc load acme/my-app --bind=cache:redis.prod`. In this scenario, your service's configuration can pull configuration values from the `redis.prod` service group, enabling it to use Redis as a caching layer. - -* A service may can optionally bind one of several services; if bind "X" is mapped, operate _this_ way; if "Y" is mapped, operate _that_ way. An application that could use either a Redis backend or a PostgreSQL backend, depending on the deployment scenario, could declare optional "redis" and "postgresql" bindings, and pick which one to map at service load-time. If this is your use case, Chef Habitat does not have a way to encode the fact that "one and only one of these optional bindings should be mapped", so you will have to manage that on your own. - -### Service Start-up Behavior - -Prior to Chef Habitat 0.56.0, if the service group that you bound to was not present in the Supervisor network census, or had no live members, your service would not start until the group was present with live members. While this can be desirable behavior in some cases, as with running certain legacy applications, it is not always desirable, particularly for modern microservice applications, which should be able to gracefully cope with the absence of their networked dependencies. - -With 0.56.0, however, this behavior can be modified using the new runtime service option `--binding-mode`. By setting `--binding-mode=relaxed` when loading a service, that service can start immediately, whether there are any members of a bound service group present or not. (Setting `--binding-mode=strict` will give you the previous, start-only-after-all-bound-groups-are-present behavior. This is also the current default, though `relaxed` will be the eventual default for Chef Habitat 1.0.0.). Such a service should have configuration and lifecycle hook templates written in such a way that the service can remain operational (though perhaps with reduced functionality) when there are no live members of a bound service group present in the network census. - -#### The Difference Between Required Binds, Optional Binds, and Binding Mode - -While there is a bit of overlap in these concepts, they are distinct. It's best to think of required and optional binds as defining "how applications can be wired together" (specifically, which "wires" must be connected in order to provide the minimal amount of information needed to run a service). Binding mode, on the other hand, defines how the application's start-up behavior is affected the presence or absence of its networked dependencies. - -Another useful thing to keep in mind when thinking about required and optional binds is that service group mappings currently cannot be dynamically changed at runtime. They can only be changed by stopping a service, reloading the service with a new set of options, and then starting it up again. This constraint (which may change in future versions of Chef Habitat) may help guide your choice between what should be a required bind, and what should be optional, particularly when using the relaxed binding mode. - -### Using Runtime Binds with Consumer Services - -Once you've defined both ends of the contract, you can leverage the bind in any of your package's hooks or configuration files. Given the two example services above, a section of a configuration file for `session-server` might look like this: - -```handlebars -{{~#each bind.database.members as |member|}} - database = "{{member.sys.ip}}:{{member.cfg.port}}" - database-secure = "{{member.sys.ip}}:{{member.cfg.ssl-port}}" -{{~/each}} -``` - -Here, `bind.` will be "truthy" (and can thus be used in boolean expressions) only if the bind has been satisfied, and `bind..members` will be an array of only active members. - -(Prior to Chef Habitat 0.56.0, `bind.` was always present, and `bind..members` had _all_ members, even ones that had left the Supervisor network long ago. This necessitated using the `eachAlive` helper function, instead of just `each`.) - -### Starting a Consumer Service - -Since your application server defined `database` as a required bind, you'll need to provide the name of a service group running a package which fulfills the contract using the `--bind` parameter to the Supervisor. For example, running the following: - -```bash -hab svc load / --bind database:amnesia.default -``` - -would create a bind aliasing `database` to the `amnesia` service in the `default` service group. - -The service group passed to `--bind database:{service}.{group}` doesn't *need* to be the service `amnesia`. This bind can be any service as long as they export a configuration key for `port` and `ssl-port`. - -You can declare bindings to multiple service groups in your templates by using the `--bind` option multiple times on the command line. Your service will not start if your package has declared a required bind and a value for it was not specified by `--bind`. - diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/pkg_build.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/pkg_build.md deleted file mode 100644 index 29f1ea71d7..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/pkg_build.md +++ /dev/null @@ -1,230 +0,0 @@ -+++ -title = "Building Packages" -description = "Building Packages in the Studio" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Building Packages" - identifier = "habitat/packages/pkg-build Build your Package" - parent = "habitat/packages" - weight = 10 -+++ - -When you have finished creating your plan and call `build` in Chef Habitat Studio, the build script does following steps: - -1. Checks that Studio has the private origin key is available to sign the artifact -2. Downloads the source code from the location in `pkg_source`, if specified -3. Validates checksum of the downloaded file using the `pkg_shasum` value, if it is specified. -4. Extracts the source into a temporary cache. -5. Builds and installs the binary or library using `make` and `make install` for Linux based builds, and - TODO: WHAT DOES WINDOWS USE? Invoke-Unpack function with Start-Process? Invoke-Install & Copy-Item? unless the callback methods are overridden in the plan. -6. Compresses the package contents (binaries, runtime dependencies, libraries, assets, etc.) into a tarball. -7. Signs the tarball with your private origin key and gives it a `.hart` file extension. - -After the build script completes, you can then upload your package to Chef Habitat Builder, or install and start your package locally. - -Packages need to be signed with a private origin key at buildtime. Generate an origin key pair manually by running the following command on your host machine: - -```bash -hab origin key generate -``` - -The `hab-origin` subcommand will place the origin key files, originname-_timestamp_.sig.key (the private key) and originname-_timestamp_.pub files (the public key), in the `$HOME/.hab/cache/keys` directory. If you're creating origin keys in the Studio container, or you are running as root on a Linux machine, your keys will be stored in `/hab/cache/keys`. - -Because the private key is used to sign your artifact, it should not be shared freely; however, if anyone wants to download and use your artifact, then they must have your public key (.pub) installed in their local `$HOME/.hab/cache/keys` or `/hab/cache/keys` directory. If the origin's public key is not present, Chef Habitat attempts to download it from the Builder endpoint specified by the `--url` argument (https://bldr.habitat.sh by default) to `hab pkg install`. - -### Passing Origin Keys into the Studio - -The Habitat Studio is a self-contained and minimal environment, which means that you'll need to share your private origin keys with the Studio to sign artifacts. You can do this in three ways: - -1. Set `HAB_ORIGIN` to the name of the origin you intend to use before entering the Studio: - - ```bash - export HAB_ORIGIN=originname - ``` - - This approach overrides the `HAB_ORIGIN` environment variable and imports your public and private origin keys into the Studio environment. It also overrides any `pkg_origin` values in the packages that you build. This is useful because you can use it to build your own artifact, as well as to build your own artifacts from other packages' source code, for example, `originname/node` or `originname/glibc`. - -1. Set `HAB_ORIGIN_KEYS` to the names of your origins. If you're using more than one origin, separate them with commas: - - ```bash - export HAB_ORIGIN_KEYS=originname-internal,originname-test,originname - ``` - - This imports the private origin keys, which must exactly match the origin names for the plans you intend to build. - -1. Use the `-k` flag (short for "keys") which accepts one or more key names separated by commas with: - - ```bash - hab studio -k originname-internal,originname-test enter - ``` - - This imports the private origin keys, which must exactly match the origin names for the plans you intend to build. - -After you create or receive your private origin key, you can start up the Studio and build your artifact. - -### Interactive Build - -Any build that you perform from a Chef Habitat Studio is an interactive build. Studio interactive builds allow you to examine the build environment before, during, and after the build. - -The directory where your plan is located is known as the plan context. - -1. Change to the parent directory of the plan context. -1. Create and enter a new Chef Habitat Studio. If you have defined an origin and origin key during `hab cli setup` or by explicitly setting the `HAB_ORIGIN` and `HAB_ORIGIN_KEYS` environment variables, then type the following: - - ```bash - hab studio enter - ``` - - The directory you were in is now mounted as `/src` inside the Studio. By default, a Supervisor runs in the background for iterative testing. You can see the streaming output by running sup-log. Type Ctrl-C to exit the streaming output and sup-term to terminate the background Supervisor. If you terminate the background Supervisor, then running sup-run will restart it along with every service that was previously loaded. You have to explicitly run hab svc unload origin/package to remove a package from the "loaded" list. - -3. Enter the following command to create the package. - - ```bash - build /src/planname - ``` - -4. If the package builds successfully, it is placed into a `results` directory at the same level as your plan. - -#### Managing the Studio Type (Docker/Linux/Windows) - -Depending on the platform of your host and your Docker configuration, the behavior of `hab studio enter` may vary. Here is the default behavior listed by host platform: - -* **Linux** - A local chrooted Linux Studio. You can force a Docker based studio by adding the `-D` flag to the `hab studio enter` command. -* **Mac** - A Docker container based Linux Studio -* **Windows** - A local Windows studio. You can force a Docker based studio by adding the `-D` flag to the `hab studio enter` command. The platform of the spawned container depends on the mode your Docker service is running, which can be toggled between Linux Containers and Windows Containers. Make sure your Docker service is running in the correct mode for the kind of studio you wish to enter. - -> Note: For more details related to Windows containers see [Running Chef Habitat Windows Containers]({{< relref "running_habitat_windows_containers" >}}). - -#### Building Dependent Plans in the Studio - -Writing plans for multiple packages that are dependent on each other can prove cumbersome when using multiple studios, as you need update dependencies frequently. On the other hand, using a single studio allows you to quickly test your changes by using locally built packages. To do so, you should use a folder structure like this: - -```bash -tree projects - -projects/ -├── project-a -└── project-b -``` - -This way, you can `hab studio enter` in `projects/`. If `project-b` depends on `project-a`, you can call `build project-a && build project-b` for example. - -### Non-interactive Build - -A non-interactive build is one in which Chef Habitat creates a Studio for you, builds the package inside it, and then destroys the Studio, leaving the resulting `.hart` on your computer. Use a non-interactive build when you are sure the build will succeed, or in conjunction with a continuous integration system. - -1. Change to the parent directory of the plan context. -1. Build the artifact in an unattended fashion, passing the name of the origin key to the command. - - ```bash - hab pkg build yourpackage -k yourname - ``` - - > Similar to the `hab studio enter` command above, the type of studio where the build runs is determined by your host platform and `hab pkg build` takes the same `-D` flag to force a Docker environment if desired. - -1. The resulting artifact is inside a directory called `results`, along with any build logs and a build report (`last_build.env`) that includes machine-parsable metadata about the build. - -By default, the Studio is reset to a clean state after the package is built; however, *if you are using the Linux version of `hab`*, you can reuse a previous Studio when building your package by specifying the `-R` option when calling the `hab pkg build` subcommand. - -For information on the contents of an installed package, see [Package contents]({{< relref "package_contents" >}}). - -## Troubleshooting Builds - -### Bash Plans: `attach` - -While working on plans, you may wish to stop the build and inspect the environment at any point during a build phase (e.g. download, build, unpack, etc.). In Bash-based plans, Chef Habitat provides an `attach` function for use in your plan.sh that functions like a debugging breakpoint and provides an easy REPL at that point. For PowerShell-based plans, you can use the PowerShell built-in `Set-PSBreakpoint` cmdlet prior to running your build. - -To use `attach`, insert it into your plan at the point where you would like to use it, e.g. - -```bash - do_build() { - attach - make - } -``` - -Now, perform a [build]({{< relref "pkg_build" >}}) -- we recommend using an interactive studio so you do not need to set up the environment from scratch for every build. - -```bash -hab studio enter -``` - -```studio -build yourapp -``` - -The build system will proceed until the point where the `attach` function is invoked, and then drop you into a limited shell: - -```bash -## Attaching to debugging session -From: /src/yourapp/plan.sh @ line 15 : - - 5: pkg_maintainer="The Chef Habitat Maintainers " - 6: pkg_source=http://download.yourapp.io/releases/${pkg_name}-${pkg_version}.tar.gz - 7: pkg_shasum=c2a791c4ea3bb7268795c45c6321fa5abcc24457178373e6a6e3be6372737f23 - 8: pkg_bin_dirs=(bin) - 9: pkg_build_deps=(core/make core/gcc) - 10: pkg_deps=(core/glibc) - 11: pkg_exports=( - 12: [port]=srv.port - 13: ) - 14: - 15: do_build() { - => 16: attach - 17: make - 18: } - -[1] yourapp(do_build)> -``` - -You can use basic Linux commands like `ls` in this environment. You can also use the `help` command the Chef Habitat build system provides in this context to see what other functions can help you debug the plan. - -```studio -[1] yourapp(do_build)> help -Help - help Show a list of command or information about a specific command. - -Context - whereami Show the code surrounding the current context - (add a number to increase the lines of context). - -Environment - vars Prints all the environment variables that are currently in scope. - -Navigating - exit Pop to the previous context. - exit-program End the /hab/pkgs/core/hab-plan-build/0.6.0/20160604180818/bin/hab-plan-build program. - -Aliases - @ Alias for `whereami`. - quit Alias for `exit`. - quit-program Alias for `exit-program`. -``` - - Type `quit` when you are done with the debugger, and the remainder of the build will continue. If you wish to abort the build entirely, type `quit-program`. - -### PowerShell Plans: `Set-PSBreakpoint` - -While there is no `attach` function exposed in a `plan.ps1` file, one can use the native Powershell cmdlet `Set-PSBreakpoint` to access virtually the same functionality. Instead of adding `attach` to your `Invoke-Build` function, enter the following from inside your studio shell: - -```powershell -[HAB-STUDIO] Habitat:\src> Set-PSBreakpoint -Command Invoke-Build -``` - -Now upon running `build` you should enter an interactive prompt inside the context of the Invoke-Build function: - -```powershell - habitat-aspnet-sample: Building -Entering debug mode. Use h or ? for help. - -Hit Command breakpoint on 'Invoke-Build' - -At C:\src\habitat\plan.ps1:26 char:23 -+ function Invoke-Build { -+ ~ -[HAB-STUDIO] C:\hab\cache\src\habitat-aspnet-sample-0.2.0>> -``` - -You can now call Powershell commands to inspect variables (like `Get-ChildItem variable:\`) or files to debug your build. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/pkg_exports.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/pkg_exports.md deleted file mode 100644 index e95dc50567..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/pkg_exports.md +++ /dev/null @@ -1,213 +0,0 @@ -+++ -title = "Exporting Packages" -description = "Export Chef Habitat packages to Docker, Kubernetes, Helm, Mesos, DC/OS, Cloud Foundry, or as a tarball " -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Exporting Packages" - identifier = "habitat/packages/pkg-exports Export Chef Habitat Packages" - parent = "habitat/packages" - weight = 40 -+++ - -Chef Habitat Artifacts--`.hart` files--can be exported in a number of different formats depending on what you need and where you need it. This is powerful because you can use the same immutable Chef Habitat artifact by exporting it into a format that you need for a specific job. - -You can export packages into several different external, immutable runtime formats. Currently there are exports for: docker, mesos, tar, and cloudfoundry. - -The command to export a package is `hab pkg export `. See the [Chef Habitat CLI Reference Guide]({{< relref "habitat_cli#hab-pkg-export" >}}) for more CLI information. - -> **Note** If you specify an `origin/package` identifier, such as `core/postgresql`, the Chef Habitat CLI will check Builder for the latest stable version of the package and export that. - -> If you wish to export a package that is not on Builder, create a Chef Habitat artifact by running the `build` command, then point `hab pkg` to the `.hart` file within the `/results` directory: - -```bash -hab pkg export tar ./results/example-app.hart -``` - -Read on for more detailed instructions. - -### Exporting to Docker - -You can create a Docker container image for any package by performing the following steps: - -1. Ensure you have a Docker daemon running on your host system. On Linux, the exporter shares the Docker socket (`unix:///var/run/docker.sock`) into the studio. - -1. Create an interactive studio with the `hab studio enter` command. - -1. [Build]({{< relref "pkg_build" >}}) the Chef Habitat package from which you want to create a Docker container image and then run the Docker exporter on the package. - - ```bash - hab pkg export docker ./results/.hart - ``` - - > **Note** The command above is for local testing only. If you have uploaded your package to Builder, you can export it by calling `hab pkg export docker origin/package`. The default is to use the latest stable release; however, you can override that by specifying a different channel in an optional flag. - - > **Note** On Linux, exporting your Chef Habitat artifact to a Docker image requires the Docker Engine supplied by Docker. Packages from distribution-specific or otherwise alternative providers are currently not supported. - - > **Note** In a Windows container studio, the `export` command will not be able to access the host docker engine. To export a Windows package or hart file built inside of a Windows container studio, first exit the studio and then export the `.hart` file in your local `results` directory. - -1. You may now exit the studio. The new Docker image exists on your computer and can be examined with `docker images` or run with `docker run`. - -1. Please note that when you run this docker container, you will need to pass the `HAB_LICENSE` environment variable into the container in order to accept the Habitat license. If you don't, your container will abort at a license acceptance prompt. One way to do this would be `docker run --env HAB_LICENSE=accept-no-persist IMAGE`. Alternatively, if you use a scheduler to run these docker containers, you should add that environment variable to your scheduler configuration. - -### Exporting to a Tarball - -1. Enter the Chef Habitat studio by using `hab studio enter`. - -2. Install or [build]({{< relref "pkg_build" >}}) the Chef Habitat package from which you want to create a tarball, for example: - - ```bash - hab pkg install / - ``` - -3. Run the tar exporter on the package. - - ```bash - hab pkg export tar / - ``` - - If you receive an error, try running - - ```bash - hab pkg export tar /results/.hart - ``` - -4. Your package is now in a tar file that exists locally on your computer in the format `---.tar.gz` and can be deployed and run on a target machine. - -5. If you wish to run this tar file on a remote machine (i.e. a virtual machine in a cloud environment), scp (or whatever transfer protocol you prefer) the file to whatever you wish to run it. - -6. SSH into the virtual machine - -7. Run these commands to set up the required user and group: - - ```bash - sudo adduser --group hab - sudo useradd -g hab hab - ``` - -8. Next, unpack the tar file: - - ```bash - sudo tar xf your-origin-package-version-timestamp.tar.gz - sudo cp -R hab /hab - ``` - -9. Now, start the Supervisor and load your service package using the `hab` binary, which is included in the tar archive: - - ```bash - sudo /hab/bin/hab sup run - sudo /hab/bin/hab svc load / - ``` - -### Exporting to Apache Mesos and DC/OS - -1. Create an interactive studio in any directory with the `hab studio enter` command. - -2. Install or [build]({{< relref "pkg_build" >}}) the Chef Habitat package from which you want to create a Marathon application, for example: - - ```bash - hab pkg install / - ``` - -3. Run the Mesos exporter on the package. - - ```bash - hab pkg export mesos / - ``` - -4. This will create a Mesos container-format tarball in the results directory, and also print the JSON needed to load the application into Marathon. Note that the tarball needs to be uploaded to a download location and the "uris" in the JSON need to be updated manually. This is an example of the output: - - ```json - { "id": "yourorigin/yourpackage", "cmd": "/bin/id -u hab &>/dev/null || /sbin/useradd hab; /bin/chown -R hab:hab *; - mount -t proc proc proc/; mount -t sysfs sys sys/;mount -o bind /dev dev/; /usr/sbin/chroot . ./init.sh start - yourorigin/yourpackage", "cpus": 0.5, "disk": 0, "mem": 256, "instances": 1, "uris": - ["https://storage.googleapis.com/mesos-habitat/yourorigin/yourpackage-0.0.1-20160611121519.tgz" ] } - ``` - -5. Note that the default resource allocation for the application is very small: 0.5 units of CPU, no disk, one instance, and 256MB of memory. To change these resource allocations, pass different values to the Mesos exporter as command line options (defaults are documented with `--help`). - -6. See the [Apaches Mesos and DC/OS documentation]({{< relref "mesos_dcos" >}}) for more information on getting your application running on Mesos. - -### Exporting to Cloud Foundry - -Packages can be exported to run in a [Cloud Foundry platform](https://www.cloudfoundry.org/certified-platforms/) through the use of a Docker image that contains additional layers meant to handle mapping from the Cloud Foundry environment to a Chef Habitat default.toml file. - -#### Setting up Docker Support in Cloud Foundry - -If you have not done so already, you must enable Docker support for Cloud Foundry before you can upload your Cloud Foundry-specific Docker image. - -To do so, make sure you have done the following: - -1. Log in as an Admin user. -2. Enable Docker support on your Cloud Foundry deployment by enabling the `diego_docker` feature flag. - -```bash -cf enable-feature-flag diego_docker -``` - -#### Creating a Mapping File - -The mapping file is a TOML file that can add Bash-interpolated variables and scripts. The Bash code will have access to: - -* all environment variables -* the jq binary -* the helper methods listed below - -Here's an example of a mapping TOML file named `cf-mapping.toml`: - -```toml cf-mapping.toml -secret_key_base = "$SECRET_KEY_BASE" -rails_env = "$RAILS_ENV" -port = ${PORT} - -[db] -user = "$(service "elephantsql" '.credentials.username')" -password = "$(service "elephantsql" '.credentials.password')" -host = "$(service "elephantsql" '.credentials.host')" -name = "$(service "elephantsql" '.credentials.database')" -``` - -#### Helpers - -The helper methods are designed to extract information from the standard Cloud Foundry environment variables [VCAP_SERVICES](https://docs.cloudfoundry.org/devguide/deploy-apps/environment-variable.html#VCAP-SERVICES) and [VCAP_APPLICATION](https://docs.cloudfoundry.org/devguide/deploy-apps/environment-variable.html#VCAP-APPLICATION). - -* `service ` will extract the JSON associated with the given service-name from the `VCAP_SERVICES` environment variable and apply the jq-expression to it. -* `application ` will apply the jq-expression to the `VCAP_APPLICATION` environment variable - -### Exporting and Pushing to a Cloud Foundry Endpoint - -1. Create a mapping.toml file using the format specified above and place that file in your local project repo. - -2. Enter the Studio through `hab studio enter`. - -3. Install or [build]({{< relref "pkg_build" >}}) the package that you want to export. - - ```bash - hab pkg install / - ``` - -4. Run the Cloud Foundry exporter on the package. - - ```bash - hab pkg export cf / /path/to/mapping.toml - ``` - - > **Note** To generate this image, a base Docker image is also created. The Cloud Foundry version of the docker image will have `cf-` as a prefix in the image tag. - -5. (Optional) If you are creating a web app that binds to another Cloud Foundry service, such as ElephantSQL, you must have this service enabled in your deployment before running your app. - -6. [Upload your Docker image to a supported registry](https://docs.cloudfoundry.org/devguide/deploy-apps/push-docker.html). Your Docker repository should be match the `origin/package` identifier of your package. - - ```bash - docker push origin/package:cf-version-release - ``` - -7. After your Cloud Foundry Docker image is built, you can deploy it to a Cloud Foundry platform. - - ```bash - cf push APP-NAME --docker-image docker_org/repository - ``` - - Your application will start after it has been successfully uploaded and deployed. - diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/pkg_ids.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/pkg_ids.md deleted file mode 100644 index 86614e6f96..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/pkg_ids.md +++ /dev/null @@ -1,33 +0,0 @@ -+++ -title = "Package Identifiers" -description = "How to call a package in Chef Habitat Builder, Studio, and plan files" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Package Identifiers" - identifier = "habitat/reference/pkg_ids Package ID" - parent = "habitat/reference" -+++ - -A Chef Habitat artifact the binary distribution for a given package built with Chef Habitat. A Chef Habitat artifact is a signed tarball with a `.hart` file extension. Chef Habitat artifacts are composed of a software library or application, the configuration information for that software, and lifecycle hooks. They are created from a the plan file, a `plan.sh` on Linux systems or a `plan.ps1` on Windows systems, and are built with Chef Habitat tools. Chef Habitat artifacts can be exported to a specific format, such as when creating a Docker image. - -When referring to Chef Habitat artifacts from either Builder or the Studio, you can refer to them in two ways: - -- Fully-qualified package identifier (FQPI) - Uses four components in the following format: `origin/name/version/release`. For example, `core/glibc/2.22/20160310192356`. -- Short package identifier - Uses two components in the following format `origin/name`. For example, `core/redis` or `core/openssl`. Use the three-component form `origin/name/version`, such as `core/redis/5.0.4`, when you need a specific version of an artifact. - -## Package Identifier Components - -- `Origin`: A name that defines a set of related Chef Habitat packages and the artifacts they generate. For example, "sample", "core", or "mycompany". -- `Name`: The name of the application or service. For example, "postgres". -- `Version`: The version number designation by the author(s) of the application or service. For example, "3.1.1", or "20160118". -- `Release`: The unique Chef Habitat id for a given version based on the timestamp pattern _YYYYMMDDhhmmss_. For example, "20160204220358" would be a Chef Habitat artifact built at 22:03:58 on February 4th, 2016. - -## Package Lookup - -If the Chef Habitat artifact identifier isn't fully qualified (having fewer than four components), and exactly one artifact is required, then the missing components are assumed to be the most recent values. For example: - -- `core/glibc` assumes that version and release values are for the latest version of core/glibc. -- `core/glibc/2.22` assumes that the version of core/glibc is 2.22 and that the release is for the most recent value of core/glibc/2.22. -- `core/glibc/2.22/20160310192356` only refers to the specific Chef Habitat artifact 20160310192356. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/pkg_promote.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/pkg_promote.md deleted file mode 100644 index 78795c1601..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/pkg_promote.md +++ /dev/null @@ -1,74 +0,0 @@ -+++ -title = "Promote Packages" -description = "Best practices for promoting packages in channels for building and testing code changes as part of continuous deployment with channel tags" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Promoting Packages" - identifier = "habitat/packages/promote Promoting Packages" - parent = "habitat/packages" - weight = 20 - -+++ - -Continuous deployment is a well-known software development practice of building and testing code changes in preparation for a release to a production environment. - -## Continuous Deployment Using Channels - -Chef Habitat supports continuous deployment workflows through the use of channels. A channel is a tag for a package that the Supervisors in a service group can subscribe to. Channels are useful in CI/CD scenarios where you want to gate a package before making it the default version of the package that users should consume. You can think of this split as the difference between test and production, or nightly releases versus stable releases of products. - -By default, every new package is placed in the `unstable` channel by Builder. Packages in the `unstable` channel cannot be started or installed unless you specify the `--channel` flag in the `hab` CLI, or set the `HAB_BLDR_CHANNEL` environment variable to a non-stable channel. This is because the default channel used by the `hab` CLI when starting, installing, or loading packages is the `stable` channel. The `stable` channel indicates a level of stability and functionality suitable for use in multi-service applications or as a dependency for your service. - -To promote your package to a channel, you must either use Builder to build your package or upload it to Builder yourself, and then use the `hab pkg promote` subcommand to promote the package to the intended channel. To combine operations, the `hab` CLI allows you to do both in one command by using the `--channel` option when uploading your package. The following shows how to upload and promote a package to a custom channel named `test`. - -```bash -$ hab pkg upload -z results/ --channel test -``` - -In the example above, if you look up your package in the Builder UI, or using the `hab pkg channels` subcommand, you can see that your package is tagged for both the `test` and `unstable` channels. - -> **Note** Custom channels like `test` are scoped to each package. Builder does not create channels scoped to an origin, so if you want to use custom channels for future releases of a package, you must promote to those channels for each release. - -If you have already uploaded your package to a channel and wish to promote it to a different channel, use the `hab pkg promote` subcommand as shown below. - -```bash -$ hab pkg promote -z /// stable -``` - -### Combining an Update Strategy with Channels - -By using both channels and either the `at-once` or `rolling` [update strategies]({{< relref "#using-updates" >}}), you can automatically update packages in a given channel as shown below: - -![Promoting packages through channels](/images/habitat/habitat-promote-packages-through-channels.png) - -Using the infographic as a guide, a typical continuous deployment scenario would be as follows: - -1. You build a new version of your package either through Builder or through a local Studio environment and then upload it to Builder. -2. When you are ready to roll out a new version of the package, you promote that package to the channel corresponding to the intended environment (e.g. `dev`). You can have multiple service groups in the same environment pointing to different channels, or the same channel. -3. An existing set of running Supervisors in that service group see that the channel they are subscribed to has an update, so they update their underlying Chef Habitat package, coordinating with one another per their update strategy, and restart their service. -4. When you are ready, you then promote that version of your package to a new channel (e.g. `acceptance`). The running Supervisors in that group see the update and perform the same service update as in step 3. You repeat steps 3 and 4 until your package makes its way through your continuous deployment pipeline. - -Configuring a Supervisor's update strategy to point to a channel ensures that new versions of the application do not get deployed until the channel is updated, thereby preventing unstable versions from reaching environments for which they are not intended. - -To start a service with an update strategy and pointing to a channel, specify them as options when loading the service. - - $ hab svc load / --strategy rolling --channel test - -While that service is running, update your package, rebuild it, and then promote it to the same channel that the previous release of that service is currently running in (e.g. `test`). Those running instances should now update according to their update strategy. - -### Demoting a Package from a Channel - -If you need to un-associate a channel from a specific package release, you can do so using the `hab pkg demote` subcommand. Packages can be demoted from all channels except `unstable`. - -```bash -$ hab pkg demote -z /// test -``` - -The Builder UI for that package release and `hab pkg channels` will both reflect the removal of that channel. - -If you are running a package in a specific channel and demote - -> **Note** If you demote a package from the `stable` channel, then any other packages that depend on the stable version of that package will either fail to load or build depending on how that demoted packaged was used. - -> Also, downgrading to another release for a specific channel is not available at this time. This means if you run the latest release of a package from a specific channel, and demote the channel for that release, the package will not downgrade to the next most recent release from that channel. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/plan_contents.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/plan_contents.md deleted file mode 100644 index aace234b6f..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/plan_contents.md +++ /dev/null @@ -1,118 +0,0 @@ -+++ -title = "Plan Contents" -description = "Best Practices for Plans" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Plan Contents" - identifier = "habitat/plans/plan-contents" - parent = "habitat/plans" - weight = 30 -+++ - -The following is a best practice guide to how to write a production quality plan. These best practices are reflected in the requirements for a user to contribute a plan to the Chef Habitat [Core Plans](https://github.com/habitat-sh/core-plans/). - -If you haven't already, a good first step is to read [the Writing Plans]({{< relref "plan_writing/" >}}) documentation. - -## Package Metadata - -Each package plan should contain a value adhering to the guidelines for each of the following elements: - -- `pkg_description` -- `pkg_license` (in [SPDX format](https://spdx.org/licenses/)) -- `pkg_maintainer` in the format of "The Chef Habitat Maintainers " -- `pkg_name` see the section of this document on "Package Name Conventions" -- `pkg_origin` must be set to `core` -- `pkg_source` -- `pkg_upstream_url` -- `pkg_version` must be the complete version number of the software - -## Package Name Conventions - -Each package is identified by a unique string containing four sub-strings separated -by a forward slash (`/`) called a [PackageIdent]({{< relref "pkg_ids" >}}). - - `origin`/`name`/`version`/`release` - -The `origin`, `name`, and `version` values of this identifier are user defined by -setting their corresponding variable in your `plan.sh` or `plan.ps1` file while the value of -`release` is generated at build-time. - -The value of `name` should exactly match the name of the project it represents and the plan file should be located within a directory of the same name in this repository. - -> Example: The plan for the [bison project](https://www.gnu.org/software/bison/) project contains setting `pkg_name=bison` and resides in `$root/bison/plan.sh`. - -## Managing Major Versions - -There is one exception to this rule: Additional plans may be defined for projects for their past major versions by appending the major version number to its name. The plan file for this new package should be located within a directory of the same name. - -> Example: the [bison project](https://www.gnu.org/software/bison/) maintains the 2.x line along with their current major version (at time of writing: 3.x). A second plan is created as `bison2` and placed within a directory of the same name in this repository. - -Packages meeting this exception will always have their latest major version found in the package sharing the exact name of their project. A new package will be created for the previous major version following these conventions. - -> Example: the [bison project](https://www.gnu.org/software/bison/) releases the 4.x line and is continuing to support Bison 3.x. The `bison` package is copied to `bison3` and the `bison` package is updated to build Bison 4.x. - -## Plan Basic Settings - -You can read more about [basic plan settings]({{< relref "plan_writing" >}}) here. The minimum requirements for a core plan are: - -- pkg_name is set -- pkg_origin is set -- pkg_shasum is set -- pkg_description is set - -## Callbacks - -You can read more about [callbacks]({{< relref "build_phase_callbacks" >}}) here. The minimum requirement for a core plan are: - -### Callback Do's - -- `do_prepare()` (`Invoke-Prepare` in a `plan.ps1`) is a good place to set environment variables and set the table to build the software. Think of it as a good place to do patches. -- If you clone a repo from git, you must override `do_verify()` to `return 0` in a `plan.sh` or if you are authoring a `plan.ps1` then override `Invoke-Verify` with an empty implementation. - -### Callback Don't's - -- Don't call `exit` within a build phase. In a `plan.sh`, you should instead return an exit code such as `return 1` for failure, and `return 0` for success. In a `plan.ps1` you should call `Write-Exception` or `throw` an exception upon failure. -- Don't use `pkg_source` unless you are downloading something as a third party. -- Don't shell out to `hab` from inside of a callback. If you think you want to, you should use a [utility function]({{< relref "plan_helpers" >}}) instead. -- Don't call any functions or helper sthat begin with an underscore, for example `_dont_call_this_function()`. Those are internal for internal builder functions and are not supported for external use. They will break your plan if you call them. -- Don't run any code or run anything outside of a build phase or a function. - -## Application Lifecycle Hooks - -The Supervisor dynamically invokes hooks at run-time, triggered by an application lifecycle event. You can read more about [hooks]({{< relref "application_lifecycle_hooks" >}}) here. - -### Lifecycle Hook Do's - -- Do redirect `stderr` to `stdout` (e.g. with `exec 2>&1` at the start of the hook) -- Do call the command to execute with `exec ` rather than running the command directly in a Linux targeted hook. This ensures the command is executed in the same process and that the service will restart correctly on configuration changes. -- You can write to the `/var/`, `/static/`, and `/data/` directories. Access these with your `runtime configuration setting` variable. - -### Lifecycle Hook Don't's - -- Don't call `hab` or `sleep` in a hook that is not the `run` hook. You can only block the thread in a hook if it is in the `run` hook. -- Don't shell out to `hab` from within a hook. If you think you want to, you should use a [runtime configuration setting]({{< relref "service_templates" >}}) instead. If none of those will solve your problem, open an issue and tell the core team why. -- Don't use `exec` if you're running something with a pipe. It won't work. -- Don't execute commands as a `root` user or try to `sudo hab pkg install`. -- Don't edit any of the Supervisor rendered templates. -- Don't edit anything in `/hab/` directly. -- Don't write to anything in `/hab/` directly. - -## README.md - -All plans need a `README.md`. Items to strongly consider including: - -- Your name as maintainer and supporter of this plan. -- What Chef Habitat topology it uses (and the plan should have the correct topology for the technology). -- Step-by-step instructions for how to use the package. -- Describe the best update strategy for different deployments. -- Describe the configuration updates a user can make and if a full rebuild is required. -- Document how to scale the service. -- Instructions for monitoring the health of the service at the application layer. -- Describe how to call the package as an application dependency in an application. -- Describe how to integrate package into an application. - -## A repo of plans - -The best practice is to place all plan files within a `habitat` parent directory, which allows for a clean separation between your application source code and habitat specific files. However, if you maintain a separate repository solely for the purpose of storing habitat plans, then the use of a `habitat` folder may not be necessary. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/plan_helpers.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/plan_helpers.md deleted file mode 100644 index 1680903a72..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/plan_helpers.md +++ /dev/null @@ -1,304 +0,0 @@ -+++ -title = "Configuration Helpers" -description = "Define dynamic plan configuration settings with plan helpers" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Plan Configuration Helpers" - identifier = "habitat/reference/plan-helpers Plan Tuning" - parent = "habitat/reference" -+++ - -Chef Habitat allows you to use [Handlebars-based](https://handlebarsjs.com/) tuneables in your plan, and you can also use both built-in Handlebars helpers and Chef Habitat-specific helpers in defining your configuration logic. - -## Built-in Helpers - -You can use block expressions to add basic logic to your template such as checking if a value exists or iterating through a list of items. - -Block expressions use a helper function to perform the logic. -The syntax is the same for all block expressions and looks like this: - -``` -{{#helper blockname}} - {{expression}} -{{/helper}} -``` - -Chef Habitat supports the standard [built-in helpers](https://handlebarsjs.com/guide/#built-in-helpers): - -- `if` -- `unless` -- `each` -- `with` -- `lookup` -- `>` ([partials](http://handlebarsjs.com/partials.html)) -- `log` - -{{< note >}} -Per [Handlebars Paths](http://handlebarsjs.com/#paths), when using `each` in a block expression, you must reference the parent context of that block to use any user-defined configuration values referenced _within_ the block, such as those that start with `cfg`. For example, if your block looked like the following, you must reference `cfg.port` from the parent context of the block: - -```handlebars -{{#each svc.members ~}} - server {{sys.ip}}:{{../cfg.port}} - {{/each}} -``` - -{{< /note >}} - -The most common block helpers that you will probably use are the `if` and `with` helpers. - -if -: The `if` helper evaluates conditional statements. The values `false`, -0, "", as well as undefined values all evaluate to false in `if` -blocks. - -Here's an example that will only write out configuration for the unixsocket tunable if a value was set by the user: - -```handlebars -{{#if cfg.unixsocket ~}} - unixsocket {{cfg.unixsocket}} -{{/if ~}} -``` - -{{< note >}} -The `~` indicates that whitespace should be omitted when rendering. -{{< /note >}} - -TOML allows you to create sections (called [TOML tables](https://github.com/toml-lang/toml#table)) to better organize your configuration variables. For example, your `default.toml` or user defined TOML could have a `[repl]` section for variables controlling replication behavior. Here's what that looks like: - -```toml -[repl] -backlog-size = 200 -backlog-ttl = 100 -disable-tcp-nodelay = no -``` - -When writing your template, you can use the `with` helper to reduce duplication: - -```handlebars -{{#with cfg.repl ~}} - repl-backlog-size {{backlog-size}} - repl-backlog-ttl {{backlog-ttl}} - repl-disable-tcp-nodelay {{disable-tcp-nodelay}} -{{/with ~}} -``` - -Helpers can also be nested and used together in block expressions. Here is another example from the redis.config file where the `if` and `with` helpers are used together to set up `core/redis` Chef Habitat services in a leader-follower topology. - - {{#if svc.me.follower ~}} - replicaof {{svc.leader.sys.ip}} {{svc.leader.cfg.port}} - {/if ~}} - -each -: Here's an example using each to render multiple server entries: - - {{#each cfg.servers as |server| ~}} - server { - host {{server.host}} - port {{server.port}} - } - {{/each ~}} - -You can also use each with `@key` and `this`. Here is an example that takes the `[env]` section of your default.toml and makes an env file you can source from your run hook: - - {{#each cfg.env ~}} - export {{toUppercase @key}}={{this}} - {{/each ~}} - -You would specify the corresponding values in a TOML file using an [array of tables](https://github.com/toml-lang/toml#array-of-tables) like this: - - [[servers]] - host = "host-1" - port = 4545 - - [[servers]] - host = "host-2" - port = 3434 - -And for both each and unless, you can use `@first` and `@last` to specify which item in an array you want to perform business logic on. For example: - - "mongo": { - {{#each bind.database.members as |member| ~}} - {{#if @first ~}} - "host" : "{{member.sys.ip}}", - "port" : "{{member.cfg.port}}" - {{/if ~}} - {{/each ~}} - } - -{{< note >}} -The `@first` and `@last` variables also work with the Chef Habitat helper `eachAlive`, and in the example above, it would be preferable to the built-in `each` helper because it checks whether the service is available before trying to retrieve any values. -{{< /note >}} - -unless -: For `unless`, using `@last` can also be helpful when you need to optionally include delimiters. In the example below, the IP addresses of the alive members returned by the `servers` binding is comma-separated. The logic check `{{#unless @last}}, {{/unless}}` at the end ensures that the comma is written after each element except the last element. - - {{#eachAlive bind.servers.members as |member| ~}} - "{{member.sys.ip}}" - {{#unless @last ~}}, {{/unless ~}} - {{/eachAlive ~}}] - -## Plan Helpers - -Chef Habitat's templating flavour includes a number of custom helpers for writing configuration and hook files. - -toLowercase -: Returns the lowercase equivalent of the given string literal. - -```handlebars -my_value={{toLowercase "UPPER-CASE"}} -``` - -toUppercase -: Returns the uppercase equivalent of the given string literal. - -```handlebars -my_value={{toUppercase "lower-case"}} -``` - -strReplace -: Replaces all matches of a pattern within the given string literal. - -```handlebars -my_value={{strReplace "this is old" "old" "new"}} -``` - -This sets `my_value` to "this is new". - -pkgPathFor -: Returns the absolute filepath to the package directory of the package best resolved from the given package identifier. The named package must exist in the `pkg_deps` of the plan from which the template resides. The helper will return a nil string if the named package is not listed in the `pkg_deps`. As result you will always get what you expect and the template won't leak to other packages on the system. - -Example Plan Contents: - -```bash -pkg_deps=("core/jre8") -``` - -Example Template: - -```handlebars -export JAVA_HOME={{pkgPathFor "core/jre8"}} -``` - -Example pointing to specific file in core/nginx package on disk: - -```handlebars -{{pkgPathFor "core/nginx"}}/config/fastcgi.conf -``` - -eachAlive -: Iterates over a collection of members and renders the template for members that are marked alive. - -```handlebars -{{~#eachAlive bind.backend.members as |member|}} -server ip {{member.sys.ip}}:{{member.cfg.port}} -{{~/eachAlive}} -``` - -toJson -: To output configuration data as JSON, you can use the `toJson` helper. - -Given a default.toml that looks like: - -```toml -[web] - -[[servers]] -host = "host-1" -port = 4545 - -[[servers]] -host = "host-2" -port = 3434 -``` - -and a template: - -```handlebars -{{toJson cfg.web}} -``` - -when rendered, it will look like: - -```json -{ - "servers": [ - { - "host": "host-1", - "port": 4545 - }, - { - "host": "host-2", - "port": 3434 - } - ] -} -``` - -This can be useful if you have a configuration file that is in JSON format and -has the same structure as your TOML configuration data. - -toToml -: The `toToml` helper can be used to output TOML. - -Given a default.toml that looks like: - -```toml default.toml -[web] - -port = 80 -``` - -and a template: - -```handlebars -{{toToml cfg.web}} -``` - -when rendered, it will look like: - -```toml -port = 80 -``` - -This can be useful if you have an app that uses TOML as its configuration file -format, but may have not been designed for Chef Habitat, and you only need certain -parts of the configuration data in the rendered TOML file. - -toYaml -: The `toYaml` helper can be used to output [YAML](https://yaml.org/). - -Given a default.toml that looks like: - -```toml default.toml -[web] - -port = 80 -``` - -and a template: - -```handlebars -{{toYaml cfg}} -``` - -when rendered, it will look like: - -```yaml -+++ -web: - port: 80 -``` - -The helper outputs a YAML document (with a line beginning with `+++`), so it must be used to create complete documents: you cannot insert a section of YAML into an existing YAML document with this helper. - -strJoin -: The `join` helper can be used to create a string with the variables in a list with a separator specified by you. For example, where `list: ["foo", "bar", "baz"]`, `{{strJoin list ","}}` would return `"foo,bar,baz"`. - -You cannot join an object (e.g. `{{strJoin web}}`), but you could join the variables in an object (e.g. `{{strJoin web.list "/"}}`). - -strConcat -: The `concat` helper can be used to connect multiple strings into one string without a separator. For example, `{{strConcat "foo" "bar" "baz"}}` would return `"foobarbaz"`.\ - -You cannot concatenate an object (e.g. `{{strConcat web}}`), but you could concatenate the variables in an object (e.g. `{{strConcat web.list}}`). diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/plan_quickstart.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/plan_quickstart.md deleted file mode 100644 index c6f97e2ca7..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/plan_quickstart.md +++ /dev/null @@ -1,45 +0,0 @@ -+++ -title = "Plan Quickstart" -draft = false -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Plan Quickstart" - identifier = "habitat/plans/plan-quickstart Plan Quickstart" - parent = "habitat/plans" - weight = 20 -+++ - -All plans must have a `plan.sh` or `plan.ps1` at the root of the plan context. They may even include both if a package is targeting both Windows and Linux platforms. This file will be used by the `hab-plan-build` command to build your package. To create a plan, do the following: - -1. If you haven't done so already, [download the `hab` CLI]({{< relref "install_habitat/" >}}) and install it per the instructions on the download page. - -2. Run `hab cli setup` and follow the instructions in the setup script. - -3. The easiest way to create a plan is to use the `hab plan init` subcommand. This subcommand will create a directory, known as the plan context, that contains your plan file and any runtime hooks and/or templated configuration data. - - To use `hab plan init` as part of your project repo, navigate to the root of your project repo and run `hab plan init`. It will create a new `habitat` sub-directory with a plan.sh (or plan.ps1 on Windows) based on the name of the parent directory, and include a `default.toml` file as well as `config` and `hooks` directories for you to populate as needed. For example: - - ```bash - cd /path/to/ - hab plan init - ``` - - will result in a new `habitat` directory located at `/path/to//habitat`. A plan file will be created and the `pkg_name` variable will be set to _\_. Also, any environment variables that you have previously set (such as `HAB_ORIGIN`) will be used to populate the respective `pkg_*` variables. - - If you want to auto-populate more of the `pkg_*` variables, you also have the option of setting them when calling `hab plan init`, as shown in the following example: - - ```bash - env pkg_svc_user=someuser pkg_deps="(core/make core/coreutils)" \ - pkg_license="('MIT' 'Apache-2.0')" pkg_bin_dirs="(bin sbin)" \ - pkg_version=1.0.0 pkg_description="foo" pkg_maintainer="you" \ - hab plan init yourplan - ``` - - See [hab plan init]({{< relref "habitat_cli#hab-plan-init" >}}) for more information on how to use this subcommand. - -4. Now that you have stubbed out your plan file in your plan context, open it and begin modifying it to suit your needs. - -When writing a plan, it's important to understand that you are defining both how the package is built and the actions Chef Habitat will take when the Supervisor starts and manages the child processes in the package. The following sections explain what you need to do for each phase. - diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/plan_settings.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/plan_settings.md deleted file mode 100644 index 466d305f2c..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/plan_settings.md +++ /dev/null @@ -1,406 +0,0 @@ -+++ -title = "Plan Settings" -description = "Define basic metadata about your artifact with plan settings" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Plan Settings" - identifier = "habitat/reference/plan-settings" - parent = "habitat/reference" -+++ - -Habitat reserves some names for internal use. You can set all of these values in your plan and use them as variables in your Habitat code. - -For example: - -```bash plan.sh -# Set the packag name -pkg_name=two-tier-app -# Call the package by name -${pkg_name} -``` - -```powershell plan.ps1 -# Set the packag name -pkg_name=two-tier-app -# Call the package by name -${"pkg_name"} -``` - -## General Settings - -FORMAT: -setting -: Short definition. How to use. How habitat uses. If required other settings. Type: String, array, boolean,etc. Default: if any. Optional/Required - -pkg_name -: Sets the name of the package. Can contain upper and lowercase letters, numbers, dashes, and underscores. By default, Chef Habitat uses `pkg_name`, `pkg_origin`, and `pkg_version` to create the fully-qualified package name. Type: string. _Required_. - -{{< foundation_tabs tabs-id="bash-powershell-panel" >}} - {{< foundation_tab active="true" panel-link="bash-panel" tab-text="Bash">}} - {{< foundation_tab panel-link="powershell-panel" tab-text="Powershell" >}} -{{< /foundation_tabs >}} - -{{< foundation_tabs_panels tabs-id="bash-powershell-panel" >}} - {{< foundation_tabs_panel active="true" panel-id="bash-panel" >}} - ```bash - pkg_name=zlib - ``` - {{< /foundation_tabs_panel >}} - - {{< foundation_tabs_panel panel-id="powershell-panel" >}} - ```powershell - $pkg_name="zlib" - ``` - {{< /foundation_tabs_panel >}} -{{< /foundation_tabs_panels >}} - -pkg_origin -: The name of the origin for this package. Can contain upper and lowercase letters, numbers, dashes, and underscores. The `HAB_ORIGIN` environment variable overrides the `pkg_origin` Type: string. _Required_. - -{{< foundation_tabs tabs-id="bash-powershell-panel1" >}} - {{< foundation_tab active="true" panel-link="bash-panel1" tab-text="Bash">}} - {{< foundation_tab panel-link="powershell-panel1" tab-text="Powershell" >}} -{{< /foundation_tabs >}} - -{{< foundation_tabs_panels tabs-id="bash-powershell-panel1" >}} - {{< foundation_tabs_panel active="true" panel-id="bash-panel1" >}} - ```bash - pkg_origin=Habitat - ``` - {{< /foundation_tabs_panel >}} - - {{< foundation_tabs_panel panel-id="powershell-panel1" >}} - ```powershell - $pkg_origin="Habitat" - ``` - {{< /foundation_tabs_panel >}} -{{< /foundation_tabs_panels >}} - -pkg_version -: Sets the version of the package By default, Chef Habitat uses `pkg_name`, `pkg_origin`, and `pkg_version` to create the fully-qualified package name. You can set the value through the `pkg_version()` function. Type: string. _Required_. - -{{< foundation_tabs tabs-id="bash-powershell-panel2" >}} - {{< foundation_tab active="true" panel-link="bash-panel2" tab-text="Bash">}} - {{< foundation_tab panel-link="powershell-panel2" tab-text="Powershell" >}} -{{< /foundation_tabs >}} - -{{< foundation_tabs_panels tabs-id="bash-powershell-panel2" >}} - {{< foundation_tabs_panel active="true" panel-id="bash-panel2" >}} - ```bash - pkg_version=1.2.8 - ``` - {{< /foundation_tabs_panel >}} - - {{< foundation_tabs_panel panel-id="powershell-panel2" >}} - ```powershell - $pkg_version="1.2.8" - ``` - {{< /foundation_tabs_panel >}} -{{< /foundation_tabs_panels >}} - -{{< note >}} -Habitat uses the guidelines of the semantic versioning specification to determine version order (see ). Keep in mind that including a hyphen in your version indicates that the package is a pre-release that will be given lower precedence to other versions. -{{< /note >}} - -pkg_maintainer -: The name and email address of the package maintainer. Type: string._Optional_. - -{{< foundation_tabs tabs-id="bash-powershell-panel3" >}} - {{< foundation_tab active="true" panel-link="bash-panel3" tab-text="Bash">}} - {{< foundation_tab panel-link="powershell-panel3" tab-text="Powershell" >}} -{{< /foundation_tabs >}} - -{{< foundation_tabs_panels tabs-id="bash-powershell-panel3" >}} - {{< foundation_tabs_panel active="true" panel-id="bash-panel3" >}} - ```bash - pkg_maintainer="Your Name " - ``` - {{< /foundation_tabs_panel >}} - - {{< foundation_tabs_panel panel-id="powershell-panel3" >}} - ```powershell - $pkg_maintainer="Your Name " - ``` - {{< /foundation_tabs_panel >}} -{{< /foundation_tabs_panels >}} - -pkg_license -: One or more [valid software licenses](https://spdx.org/licenses/) that relate to this package. Type: array. _Optional_. - -{{< foundation_tabs tabs-id="bash-powershell-panel4" >}} - {{< foundation_tab active="true" panel-link="bash-panel4" tab-text="Bash">}} - {{< foundation_tab panel-link="powershell-panel4" tab-text="Powershell" >}} -{{< /foundation_tabs >}} - -{{< foundation_tabs_panels tabs-id="bash-powershell-panel4" >}} - {{< foundation_tabs_panel active="true" panel-id="bash-panel4" >}} - ```bash - pkg_license=('Apache-2.0') - ``` - {{< /foundation_tabs_panel >}} - - {{< foundation_tabs_panel panel-id="powershell-panel4" >}} - ```powershell - $pkg_license=("'Apache-2.0'") - ``` - {{< /foundation_tabs_panel >}} -{{< /foundation_tabs_panels >}} - -{{< note >}} -If your package has a custom license, use a string literal matching the title of the license. For example, you'll see `pkg_license=('Boost Software License')` for the `cmake` plan. -{{< /note >}} - -pkg_source -: A URL that specifies the location from which to download an external source. Any valid `wget` url will work. Typically, the relative path for the URL typically contains the `pkg_name` and `pkg_version` values. Type: URL. _Optional_. - -{{< foundation_tabs tabs-id="bash-powershell-panel5" >}} - {{< foundation_tab active="true" panel-link="bash-panel5" tab-text="Bash">}} - {{< foundation_tab panel-link="powershell-panel5" tab-text="Powershell" >}} -{{< /foundation_tabs >}} - -{{< foundation_tabs_panels tabs-id="bash-powershell-panel5" >}} - {{< foundation_tabs_panel active="true" panel-id="bash-panel5" >}} - ```bash - pkg_source=http://downloads.sourceforge.net/project/libpng/$pkg_name/${pkg_version}/${pkg_name}-${pkg_version}.tar.gz - ``` - {{< /foundation_tabs_panel >}} - - {{< foundation_tabs_panel panel-id="powershell-panel5" >}} - ```powershell - $pkg_source="http://downloads.sourceforge.net/project/libpng/$pkg_name/${pkg_version}/${pkg_name}-${pkg_version}.tar.gz" - ``` - {{< /foundation_tabs_panel >}} -{{< /foundation_tabs_panels >}} - -pkg_filename -: The filename for the finished artifact. By default, Chef Habitat ] constructs this from `pkg_name` and `pkg_version`. Type: string. _Optional_. - -{{< foundation_tabs tabs-id="bash-powershell-panel6" >}} - {{< foundation_tab active="true" panel-link="bash-panel6" tab-text="Bash">}} - {{< foundation_tab panel-link="powershell-panel6" tab-text="Powershell" >}} -{{< /foundation_tabs >}} - -{{< foundation_tabs_panels tabs-id="bash-powershell-panel6" >}} - {{< foundation_tabs_panel active="true" panel-id="bash-panel6" >}} - ```bash - pkg_filename=${pkg_name}-${pkg_version}.tar.gz - ``` - {{< /foundation_tabs_panel >}} - - {{< foundation_tabs_panel panel-id="powershell-panel6" >}} - ```powershell - $pkg_filename="${pkg_name}-${pkg_version}.tar.gz" - ``` - {{< /foundation_tabs_panel >}} -{{< /foundation_tabs_panels >}} - -pkg_shasum -: The sha-256 sum of the downloaded `pkg_source`. If you do not have the checksum, generate it by downloading the source and using the `sha256sum` or `gsha256sum` tools. Override with `do_verify()`. When the value is unset or incorrect and you do not override it with `do_verify()`, then the build output of your package will show the expected value. Type: varchar(64) or char(64). _Required_ when providing a valid URL is provided for `pkg_source`, but is otherwise _Optional_. - -{{< foundation_tabs tabs-id="bash-powershell-panel7" >}} - {{< foundation_tab active="true" panel-link="bash-panel7" tab-text="Bash">}} - {{< foundation_tab panel-link="powershell-panel7" tab-text="Powershell" >}} -{{< /foundation_tabs >}} - -{{< foundation_tabs_panels tabs-id="bash-powershell-panel7" >}} - {{< foundation_tabs_panel active="true" panel-id="bash-panel7" >}} - ```bash - pkg_shasum=36658cb768a54c1d4dec43c3116c27ed893e88b02ecfcb44f2166f9c0b7f2a0d - ``` - {{< /foundation_tabs_panel >}} - - {{< foundation_tabs_panel panel-id="powershell-panel7" >}} - ```powershell - $pkg_shasum="36658cb768a54c1d4dec43c3116c27ed893e88b02ecfcb44f2166f9c0b7f2a0d" - ``` - {{< /foundation_tabs_panel >}} -{{< /foundation_tabs_panels >}} - -pkg_deps -: The dependencies that your packages needs at runtime. Refer to packages at three levels of specificity: origin/package, origin/package/version, or origin/package/version/release. Type: array. _Optional_. - -{{< foundation_tabs tabs-id="bash-powershell-panel8" >}} - {{< foundation_tab active="true" panel-link="bash-panel8" tab-text="Bash">}} - {{< foundation_tab panel-link="powershell-panel8" tab-text="Powershell" >}} -{{< /foundation_tabs >}} - -{{< foundation_tabs_panels tabs-id="bash-powershell-panel8" >}} - {{< foundation_tabs_panel active="true" panel-id="bash-panel8" >}} - ```bash - pkg_deps=(core/glibc core/pcre core/openssl core/zlib) - ``` - {{< /foundation_tabs_panel >}} - - {{< foundation_tabs_panel panel-id="powershell-panel8" >}} - ```powershell - $pkg_deps="(core/glibc core/pcre core/openssl core/zlib)" - ``` - {{< /foundation_tabs_panel >}} -{{< /foundation_tabs_panels >}} - -pkg_build_deps -: The dependencies your package requires at build time. Type: array. _Optional_. - -{{< foundation_tabs tabs-id="bash-powershell-panel9" >}} - {{< foundation_tab active="true" panel-link="bash-panel9" tab-text="Bash">}} - {{< foundation_tab panel-link="powershell-panel9" tab-text="Powershell" >}} -{{< /foundation_tabs >}} - -{{< foundation_tabs_panels tabs-id="bash-powershell-panel9" >}} - {{< foundation_tabs_panel active="true" panel-id="bash-panel9" >}} - ```bash - pkg_build_deps=(core/gcc core/linux-headers) - ``` - {{< /foundation_tabs_panel >}} - - {{< foundation_tabs_panel panel-id="powershell-panel9" >}} - ```powershell - $pkg_build_deps="(core/gcc core/linux-headers)" - ``` - {{< /foundation_tabs_panel >}} -{{< /foundation_tabs_panels >}} - -pkg_lib_dirs -: An array of paths, relative to the final install of the software, where libraries can be found. Used to populate `LD_FLAGS` and `LD_RUN_PATH` for software that depends on your package. _Optional_. - -```bash -pkg_lib_dirs=(lib) -``` - -pkg_include_dirs -: An array of paths, relative to the final install of the software, where headers can be found. Used to populate `CFLAGS` for software that depends on your package. _Optional_. - -```bash -pkg_include_dirs=(include) -``` - -pkg_bin_dirs -: An array of paths, relative to the final install of the software, where binaries can be found. Used to populate `PATH` for software that depends on your package. _Optional_. - -```bash -pkg_bin_dirs=(bin) -``` - -pkg_pconfig_dirs -: An array of paths, relative to the final install of the software, where pkg-config metadata (.pc files) can be found. Used to populate `PKG_CONFIG_PATH` for software that depends on your package. _Optional_. - -```bash -pkg_pconfig_dirs=(lib/pkgconfig) -``` - -pkg_svc_run -: The command for the Supervisor to execute when starting a service. This setting requires `pkg_bin_dirs` to place package binaries in the path. If your package hs complex start-up behaviors, use a [run hook]({{< relref "#hooks" >}}) instead. Omit this setting for packages that are designed for consumption by other packages instead of being run directly by a Supervisor. _Optional_. - -```bash -pkg_svc_run="haproxy -f $pkg_svc_config_path/haproxy.conf" -``` - -pkg_exports -: Configuration data that will be passed between peers. The keys in this array are used with `pkg_exposes` and for any consuming services that set `pkg_binds` or `pkg_binds_optional`. An [associative array](https://www.linuxjournal.com/content/bash-associative-arrays) in Bash or a `hashtable` in Powershell. Type: array. _Optional_. - -```bash -pkg_exports=( - [port]=server.port - [host]=server.host - [ssl-port]=ssl.port -) -``` - -In this example, the corresponding `default.toml` file would have the following key/value pairs defined: - -```toml default.toml - [server] - port = 80 - host = "www.example.com" - - [ssl] - port = 443 -``` - -pkg_exposes -: An array of `pkg_exports` keys containing default values for the ports that this package exposes. These values are used as sensible defaults for other tools, such as when exporting a package to a container format. _Optional_. - -```bash -pkg_exposes=(port ssl-port) -``` - -{{< note >}} -In addition to specifying the keys you defined in `pkg_exports`, you must have a default.toml file indicating the port values to expose. -{{< /note >}} - -pkg_binds -: An associative array (or `hashtable` in Powershell) representing services which you depend on and the configuration keys that you expect the service to export (by their `pkg_exports`). These binds *must* be set for the Supervisor to load the service. The loaded service will wait to run until its bind becomes available. If the bind does not contain the expected keys, the service will not start successfully. _Optional_. - -```bash -pkg_binds=( - [database]="port host" -) -``` - -pkg_binds_optional -: Same as `pkg_binds` but these represent optional services to connect to. _Optional_. - -```bash -pkg_binds_optional=( - [storage]="port host" -) -``` - -pkg_interpreters -: An array of interpreters used in [shebang](https://en.wikipedia.org/wiki/Shebang_(Unix)) lines for scripts. Specify the subdirectory where the binary is relative to the package, for example, `bin/bash` or `libexec/neverland`, since binaries can be located in directories besides `bin`. This list of interpreters will be written to the metadata INTERPRETERS file, located inside a package, with their fully-qualified path. Then these can be used with the fix_interpreter function. For more information on declaring shebangs in Chef Habitat, see [Plan hooks]({{< relref "#hooks" >}}), and for more information on the fix_interpreter function, see [Plan utility functions]({{< relref "#plan-helpers" >}}). _Optional_. - -```bash -pkg_interpreters=(bin/bash) -``` - -pkg_svc_user -: The user to run the service as. Default: `hab`. On Windows, if the `hab` user does not exist then the service will run under the same account as the Supervisor. _Optional_. - -```bash -pkg_svc_user=hab -``` - -pkg_svc_group -: Assigned service group for the package. **Not used in a `plan.ps1`.** Type: string. Default: `hab`. _Optional_. - -```bash -pkg_svc_group=$pkg_svc_user -``` - -pkg_shutdown_signal -: The signal to send the service to shutdown. **Not used in a `plan.ps1`.** Default: `TERM`. _Optional_. - -```bash -pkg_shutdown_signal=HUP -``` - -pkg_shutdown_timeout_sec -: The number of seconds to wait for a service to shutdown. After this interval the service will forcibly be killed. **Not used in a `plan.ps1`.** Default: `8`. _Optional_. - -```bash -pkg_shutdown_timeout_sec=$pkg_shutdown_timeout_sec -``` - -pkg_description -: A short description of the package. It can be a simple string, or you can create a multi-line description using markdown to provide a rich description of your package. This description will be displayed on the Web app when users search for or browse to your package. Type: Text._Required_ for [core](https://github.com/habitat-sh/core-plans) plans, but otherwise _Optional_. - -```bash -pkg_description=$(cat << EOF - # My package description - This is the package for the foo library. It's pretty awesome. - EOF - ) -``` - -{{< note >}} -Escape all special characters other than `#`. The hab-plan-build script interprets unescaped characters as code during the package build. -{{< /note >}} - -pkg_upstream_url -: An upstream project homepage or website URL. _Optional_. - -```bash -pkg_upstream_url=https://github.com/myrepo -``` diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/plan_variables.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/plan_variables.md deleted file mode 100644 index 809eafbf5a..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/plan_variables.md +++ /dev/null @@ -1,90 +0,0 @@ -+++ -title = "Plan Variables" -description = "Set package, service, and cache paths, compiler options, install location and context with plan variables" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Plan Variables" - identifier = "habitat/reference/plan-variables" - parent = "habitat/reference" -+++ - -The following variables can be used in your plans to help get binaries and libraries -to build and install in the correct locations in your package. The values for the -variables listed below are default values or read-only values. - -pkg_prefix -: The absolute path for your package. - -pkg_dirname -: The directory created when Habitat extracts an archive. - - If a .tar file extracts to a directory that's different from the filename, then you would need to override this value to match the directory name created during extraction. - - Default value: `${pkg_name}-${pkg_version}` - -pkg_svc_path -: Where the running service is located. - - Read-only value: `${HAB_ROOT_PATH}/svc/${pkg_name}` - -pkg_svc_data_path -: Where the running service data is located. - - Read-only value: `${pkg_svc_path}/data` - -pkg_svc_files_path -: Where the gossiped configuration files are located. - - Read-only value: `${pkg_svc_path}/files` - -pkg_svc_var_path -: Where the running service variable data is located. - - Read-only value: `${pkg_svc_path}/var` - -pkg_svc_config_path -: Where the running service configuration is located. - - Read-only value: `${pkg_svc_path}/config` - -pkg_svc_static_path -: Where the running service static data is located. - - Read-only value: `${pkg_svc_path}/static` - -CACHE_PATH -: A temporary directory that will be clean on every build. - - Read-only value: `${HAB_CACHE_SRC_PATH}/${pkg_dirname}` - -HAB_CACHE_SRC_PATH -: The default path where source archives are downloaded, extracted, and compiled. - - Read-only value: `${HAB_ROOT_PATH}/cache/src` - -HAB_CACHE_ARTIFACT_PATH -: The default download root path for packages. - - Read-only value: `${HAB_ROOT_PATH}/cache/artifacts` - -HAB_PKG_PATH -: The root path containing all locally installed packages. - - Read-only value: `${HAB_ROOT_PATH}/pkgs` - -PLAN_CONTEXT -: The location on your local dev machine for the files in your plan directory. - -CFLAGS -: C compiler options. - -LDFLAGS -: C linker options. - -PREFIX -: Where to install the software; same as `pkg_prefix`. - -LD_RUN_PATH -: Where to find the binaries at run time. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/plan_writing.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/plan_writing.md deleted file mode 100644 index 2d417eb927..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/plan_writing.md +++ /dev/null @@ -1,296 +0,0 @@ -+++ -title = "Writing Plans" -description = "Documentation for writing Chef Habitat Plan files including configuration templates, binds, and exporting" -aliases = ["/habitat/developing-packages/"] -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Plan Writing" - identifier = "habitat/plans/plan-writing Chef Habitat Plan Overview" - parent = "habitat/plans" - weight = 10 -+++ - -In Chef Habitat the unit of automation is the application itself. This chapter includes content related specifically to the process and workflow of developing a plan that will instruct Chef Habitat in how to build, deploy, and manage your application. - -## Writing Plans - -Artifacts are the cryptographically-signed tarballs that are uploaded, downloaded, unpacked, and installed in Chef Habitat. They are built from shell scripts known as plans, but may also include application lifecycle hooks and service configuration files that describe the behavior and configuration of a running service. - -At the center of Chef Habitat packaging is the plan. This is a directory comprised of shell scripts and optional configuration files that define how you download, configure, make, install, and manage the lifecycle of the software in the artifact. More conceptual information on artifacts can be found in the [Package Identifiers]({{< relref "pkg_ids" >}}) page. - -As a way to start to understand plans, let's look at an example `plan.sh` for [sqlite](https://www.sqlite.org/): - -```bash plan.sh -pkg_name=sqlite -pkg_version=3130000 -pkg_origin=core -pkg_license=('Public Domain') -pkg_maintainer="The Chef Habitat Maintainers " -pkg_description="A software library that implements a self-contained, serverless, zero-configuration, transactional SQL database engine." -pkg_upstream_url=https://www.sqlite.org/ -pkg_source=https://www.sqlite.org/2016/${pkg_name}-autoconf-${pkg_version}.tar.gz -pkg_filename=${pkg_name}-autoconf-${pkg_version}.tar.gz -pkg_dirname=${pkg_name}-autoconf-${pkg_version} -pkg_shasum=e2797026b3310c9d08bd472f6d430058c6dd139ff9d4e30289884ccd9744086b -pkg_deps=(core/glibc core/readline) -pkg_build_deps=(core/gcc core/make core/coreutils) -pkg_lib_dirs=(lib) -pkg_include_dirs=(include) -pkg_bin_dirs=(bin) -``` - -> Note: On Windows we would create a plan.ps1 file instead. All the variable names are the same but we use Powershell syntax so, for example, `pkg_deps=(core/glibc core/readline)` becomes `$pkg_deps=@("core/glibc", "core/readline")`. - -It has the name of the software, the version, where to download it, a checksum to verify the contents are what we expect, run dependencies on `core/glibc` and `core/readline`, build dependencies on `core/coreutils`, `core/make`, `core/gcc`, libraries files in `lib`, header files in `include`, and a binary file in `bin`. Also, because it's a core plan, it has a description and upstream URL for the source project included. - -> Note: The `core` prefix is the origin of those dependencies. For more information, see [Create an Origin]({{< relref "builder_origins" >}}) - -When you have finished creating your plan and call `build` in Chef Habitat studio, the following occurs: - -1. The build script ensures that the private origin key is available to sign the artifact. -2. If specified in `pkg_source`, a compressed file containing the source code is downloaded. -3. The checksum of that file, specified in `pkg_shasum`, is validated. -4. The source is extracted into a temporary cache. -5. Unless overridden, the callback methods will build and install the binary or library via `make` and `make install`, respectively for Linux based builds. -6. Your package contents (binaries, runtime dependencies, libraries, assets, etc.) are then compressed into a tarball. -7. The tarball is signed with your private origin key and given a `.hart` file extension. - -After the build script completes, you can then upload your package to Chef Habitat Builder, or install and start your package locally. - -> Note: The plan.sh or plan.ps1 file is the only required file to create a package. Configuration files, runtime hooks, and other source files are optional. - -## Write Your First Plan - -All plans must have a `plan.sh` or `plan.ps1` at the root of the plan context. They may even include both if a package is targeting both Windows and Linux platforms. This file will be used by the `hab-plan-build` command to build your package. To create a plan, do the following: - -1. If you haven't done so already, [download the `hab` CLI]({{< relref "install_habitat/" >}}) and install it per the instructions on the download page. - -2. Run `hab cli setup` and follow the instructions in the setup script. - -3. The easiest way to create a plan is to use the `hab plan init` subcommand. This subcommand will create a directory, known as the plan context, that contains your plan file and any runtime hooks and/or templated configuration data. - - To use `hab plan init` as part of your project repo, navigate to the root of your project repo and run `hab plan init`. It will create a new `habitat` sub-directory with a plan.sh (or plan.ps1 on Windows) based on the name of the parent directory, and include a `default.toml` file as well as `config` and `hooks` directories for you to populate as needed. For example: - - ```bash - cd /path/to/ - hab plan init - ``` - - will result in a new `habitat` directory located at `/path/to//habitat`. A plan file will be created and the `pkg_name` variable will be set to _\_. Also, any environment variables that you have previously set (such as `HAB_ORIGIN`) will be used to populate the respective `pkg_*` variables. - - If you want to auto-populate more of the `pkg_*` variables, you also have the option of setting them when calling `hab plan init`, as shown in the following example: - - ```bash - env pkg_svc_user=someuser pkg_deps="(core/make core/coreutils)" \ - pkg_license="('MIT' 'Apache-2.0')" pkg_bin_dirs="(bin sbin)" \ - pkg_version=1.0.0 pkg_description="foo" pkg_maintainer="you" \ - hab plan init yourplan - ``` - - See [hab plan init]({{< relref "habitat_cli#hab-plan-init" >}}) for more information on how to use this subcommand. - -4. Now that you have stubbed out your plan file in your plan context, open it and begin modifying it to suit your needs. - -When writing a plan, it's important to understand that you are defining both how the package is built and the actions Chef Habitat will take when the Supervisor starts and manages the child processes in the package. The following sections explain what you need to do for each phase. - -## Writing a Plan for Multiple Platform Targets - -You may want to create a plan for an application that can run on multiple platform targets. You can create target specific folders beneath either the root of your project or a top level `habitat` folder. Then save the plan, hooks, and configuration templates specific to a single platform all inside of that target specific folder. - -For example, an application targeting linux, Linux kernel 2, and Windows may have the following structure: - -``` -app_root/ -├── x86_64-linux/ -| | plan.sh -| └── hooks/ -| run -├── x86_64-linux-kernel2/ -| | plan.sh -| └── hooks/ -| run -└── x86_64-windows/ - | plan.ps1 - └── hooks/ - run -``` - -The build script will look for the base of your plan in the following locations: - -- `//` -- `/habitat//` -- `/` -- `/habitat/` - -If it finds a plan both inside as well as outside of a target folder, the target specific plan will be used as long as that is the target currently being built. However it is strongly recommended that you do not have plans both inside and outside of a target folder. We currently allow this only for backwards compatibility with some existing plans but plan to eventually fail builds where a plan exists in both places. The best practice when you need multiple plans for different targets is to put each plan in its own target folder. - -Of course if your plan does not include hooks or configuration templates and just requires a plan file, you may choose this simpler structure: - -``` -app_root/ -└── habitat/ - plan.sh - plan.ps1 -``` - -> Note: It is recommended to place all plan files inside of a `habitat` parent folder in order to allow for clean separation between your application source code and habitat specific files. However, if you maintain a separate repository solely for the purpose of storing habitat plans, then the use of a `habitat` folder may not be necessary. - -On Windows, only a `plan.ps1` will be used and a `plan.sh` will only be used on Linux or Linux kernel 2. So if your application requires different plans for Linux and Linux Kernel 2, even without hooks and configuration templates, you will need to use target folders for each platform. - -### Buildtime Workflow - -For buildtime installation and configuration, workflow steps need to be included in the plan file to define how you will install your application source files into a package. Before writing your plan, you should know and understand how your application binaries are currently built, installed, what their dependencies are, and where your application or software library expects to find those dependencies. - -The main steps in the buildtime workflow are the following: - -1. Create your fully-qualified package identifier. -2. Add licensing and contact information. -3. Download and unpack your source files. -4. Define your dependencies. -5. (Optional) Override any default build phases you need to using callbacks. - -The following sections describe each of these steps in more detail. - -#### Create your Package Identifier - -The origin is a place for you to set default privacy rules, store your packages, and collaborate with teammates. For example, the "core" origin is where the core maintainers of Chef Habitat share packages that are foundational to building other packages. If you would like to browse them, they are located in the [core-plans repo](https://github.com/habitat-sh/core-plans), and on [Chef Habitat Builder's Core Origin](https://bldr.habitat.sh/#/pkgs/core). - -Creating artifacts for a specific origin requires that you have access to the that origin's private key. The private origin key will be used to sign the artifact when it is built by the `hab plan build` command. Origin keys are kept in `$HOME/.hab/cache/keys` on the host machine when running `hab` as a non-root user and `/hab/cache/keys` when running as root (including in the studio). For more information on origin keys, see [Keys]({{< relref "keys" >}}). - -The next important part of your package identifier is the name of the package. Standard naming convention is to base the name of the package off of the name of the source or project you download and install into the package. - -#### Add Licensing and Contact Information - -You should enter your contact information in your plan. - -Most importantly, you should update the `pkg_license` value to indicate the type of license (or licenses) that your source files are licensed under. Valid license types can be found at [https://spdx.org/licenses/](https://spdx.org/licenses/). You can include multiple licenses as an array. - -> Note: Because all arrays in the pkg_* settings are shell arrays, they are whitespace delimited. - -#### Download and Unpack Your Source Files - -Add in the `pkg_source` value that points to where your source files are located at. Any `wget` url will work; however, unless you're downloading a tarball from a public endpoint, you may need to modify how you download your source files and where in your plan.sh you perform the download operation. - -Chef Habitat supports retrieving source files from [GitHub](https://github.com). When cloning from GitHub, it is recommended to use https URIs because they are proxy friendly, whereas `git@github` or `git://` are not. To download the source from a GitHub repository, implement `do_download()` in your plan.sh (or `Invoke-Download` in a plan.ps1) and add a reference the `core/git` package as a build dependency. Because Chef Habitat does not contain a system-wide CA cert bundle, you must use the `core/cacerts` package and export the `GIT_SSL_CAINFO` environment variable to point the `core/cacerts` package on Linux. Here's an example of how to do this in the `do_download()` callback. - -```bash -do_download() { - export GIT_SSL_CAINFO="$(pkg_path_for core/cacerts)/ssl/certs/cacert.pem" - git clone https://github.com/chef/chef - pushd chef - git checkout $pkg_version - popd - tar -cjvf $HAB_CACHE_SRC_PATH/${pkg_name}-${pkg_version}.tar.bz2 \ - --transform "s,^\./chef,chef-${pkg_version}," ./chef \ - --exclude chef/.git --exclude chef/spec - pkg_shasum=$(trim $(sha256sum $HAB_CACHE_SRC_PATH/${pkg_filename} | cut -d " " -f 1)) -} -``` - -The plan.ps1 equivalent would be: - -```powershell -Function Invoke-Download { - git clone https://github.com/chef/chef - pushd chef - git checkout $pkg_version - popd - Compress-Archive -Path chef/* -DestinationPath $HAB_CACHE_SRC_PATH/$pkg_name-$pkg_version.zip -Force - $script:pkg_shasum = (Get-FileHash -path $HAB_CACHE_SRC_PATH/$pkg_name-$pkg_version.zip -Algorithm SHA256).Hash.ToLower() -} -``` - -After you have either specified your source in `pkg_source`, or overridden the **do_download()** or **Invoke-Download** callback, create a sha256 checksum for your source archive and enter it as the `pkg_shasum` value. The build script will verify this after it has downloaded the archive. - -> Note: If your computed value does not match the value calculated by the `hab-plan-build` script, an error with the expected value will be returned when you execute your plan. - -If your package does not download any application or service source files, then you will need to override the **do_download()**, **do_verify()**, and **do_unpack()** callbacks. See [Callbacks]({{< relref "build_phase_callbacks" >}}) for more details. - -#### Define Your Dependencies - -Applications have two types of dependencies: buildtime and runtime. - -Declare any build dependencies in `pkg_build_deps` and any run dependencies in `pkg_deps`. You can include version and release information when declaring dependencies if your application is bound to a particular version. - -The package `core/glibc` is typically listed as a run dependency and `core/coreutils` as a build dependency, however, you should not take any inference from this. There are no standard dependencies that every package must have. For example, the mytutorialapp package only includes the `core/node` as a run dependency. You should include dependencies that would natively be part of the build or runtime dependencies your application or service would normally depend on. - -There is a third type of dependencies, transitive dependencies, that are the run dependencies of either the build or run dependencies listed in your plan. You do not need to explicitly declare transitive dependencies, but they are included in the list of files when your package is built. See [Package contents]({{< relref "package_contents" >}}) for more information. - -#### Override Build Phase Defaults with Callbacks - -As shown in an example above, there are occasions when you want to override the default behavior of the hab-plan-build script. The Plan syntax guide lists the default implementations for [build phase callbacks]({{< relref "build_phase_callbacks" >}}), but if you need to reference specific packages in the process of building your applications or services, then you need to override the default implementations as in the example below. - -```bash -pkg_name=httpd -pkg_origin=core -pkg_version=2.4.18 -pkg_maintainer="The Chef Habitat Maintainers " -pkg_license=('apache') -pkg_source=http://www.apache.org/dist/${pkg_name}/${pkg_name}-${pkg_version}.tar.gz -pkg_shasum=1c39b55108223ba197cae2d0bb81c180e4db19e23d177fba5910785de1ac5527 -pkg_deps=(core/glibc core/expat core/libiconv core/apr core/apr-util core/pcre core/zlib core/openssl) -pkg_build_deps=(core/patch core/make core/gcc) -pkg_bin_dirs=(bin) -pkg_lib_dirs=(lib) -pkg_exports=( - [port]=serverport -) -pkg_svc_run="httpd -DFOREGROUND -f $pkg_svc_config_path/httpd.conf" -pkg_svc_user="root" - -do_build() { - ./configure --prefix=$pkg_prefix \ - --with-expat=$(pkg_path_for expat) \ - --with-iconv=$(pkg_path_for libiconv) \ - --with-pcre=$(pkg_path_for pcre) \ - --with-apr=$(pkg_path_for apr) \ - --with-apr-util=$(pkg_path_for apr-util) \ - --with-z=$(pkg_path_for zlib) \ - --enable-ssl --with-ssl=$(pkg_path_for openssl) \ - --enable-modules=most --enable-mods-shared=most - make -} -``` - -In this example, the `core/httpd` plan references several other core packages through the use of the `pkg_path_for` function before `make` is called. You can use a similar pattern if you need reference a binary or library when building your source files. - -Or consider this override from a plan.ps1: - -```powershell -function Invoke-Build { - Push-Location "$PLAN_CONTEXT" - try { - cargo build --release --verbose - if($LASTEXITCODE -ne 0) { - Write-Error "Cargo build failed!" - } - } - finally { Pop-Location } -} -``` - -Here the plan is building an application written in Rust. So it overrides `Invoke-Build` and uses the `cargo` utility included in its buildtime dependency on `core/rust`. - -> Note: Powershell plan function names differ from their Bash counterparts in that they use the `Invoke` `verb` instead of the `do_` prefix. - -When overriding any callbacks, you may use any of the [variables]({{< relref "plan_variables" >}}), [settings]({{< relref "plan_settings" >}}), or [functions]({{< relref "build_helpers" >}}), except for the [runtime template data]({{< relref "service_templates" >}}). Those can only be used in Application Lifecycle hooks once a Chef Habitat service is running. - -### Runtime Workflow - -Similar to defining the setup and installation experience at buildtime, behavior for your application or service needs to be defined for the Supervisor. This is done at runtime through Application lifecycle hooks. See [Application Lifecycle hooks]({{< relref "application_lifecycle_hooks" >}}) for more information and examples. - -If you only need to start the application or service when the Chef Habitat service starts, you can instead use the `pkg_svc_run` setting and specify the command as a string. When your package is created, a basic run hook will be created by Chef Habitat. - -You can use any of the [runtime configuration settings]({{< relref "service_templates" >}}), either defined by you in your config file, or defined by Chef Habitat. - -Once you are done writing your plan, use the studio to [build your package]({{< relref "pkg_build" >}}). - -### Related Resources - -- [Write plans]({{< relref "#writing-plans" >}}): Describes what a plan is and how to create one. -- [Add configuration to plans]({{< relref "config_templates" >}}): Learn how to make your running service configurable by templatizing configuration files in your plan. -- [Binary-only packages]({{< relref "binary_wrapper" >}}): Learn how to create packages from software that comes only in binary form, like off-the-shelf or legacy programs. - -You may also find the [settings]({{< relref "plan_settings" >}}), [variables]({{< relref "plan_variables" >}}), and [functions]({{< relref "build_helpers" >}}) documentation useful when creating your plan. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/promote_packages.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/promote_packages.md deleted file mode 100644 index fe542b7ab1..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/promote_packages.md +++ /dev/null @@ -1,14 +0,0 @@ -+++ -title = "Promote Packages Through Channels" -description = "Promote Packages Through Channels" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Promote Packages Through Channels" - identifier = "habitat/diagrams/promote-packages" - parent = "habitat/diagrams" - weight = 70 -+++ - -![Chef Habitat Promote Packages Through Channels Diagram](/images/habitat/habitat-promote-packages-through-channels.png) diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/index.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/index.md deleted file mode 100644 index c33988f645..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/index.md +++ /dev/null @@ -1,7 +0,0 @@ -+++ -headless=true - -# This creates a headless bundle. -# See: https://gohugo.io/content-management/page-bundles/#headless-bundle -# and https://docs.chef.io/style_guide/reuse/#reusable-text-files -+++ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/md/builder_origins.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/md/builder_origins.md deleted file mode 100644 index 2868a9298d..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/md/builder_origins.md +++ /dev/null @@ -1,5 +0,0 @@ -An origin is a unique namespace in Chef Habitat Builder where you can store, share, and build packages. -Once created, an origin cannot be renamed, but it can be deleted or transferred. -For example, the _core_ origin contains foundational packages managed and versioned by the core Chef Habitat maintainers. - -You can join existing origins by invitation or create your own origins in an on-prem Habitat Builder deployment. For details about invitations, see [origin membership and RBAC]({{< relref "origin_rbac.md#origin-membership" >}}). diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/md/create_origins_builder.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/md/create_origins_builder.md deleted file mode 100644 index 9f24253e6f..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/md/create_origins_builder.md +++ /dev/null @@ -1,25 +0,0 @@ - -To create an origin in Chef Habitat Builder, follow these steps: - -1. In Habitat Builder, select **My Origins** in the left navigation menu. - -1. On the **My Origins** page, select **Create origin** which opens the **Create New Origin** form. - -1. Enter a unique name that you want to associate with your packages. Chef Habitat will only let you create an origin with a unique name. Some examples that you'll see in Chef Habitat Builder are team names, user names, and abstract concepts. - -1. Choose a privacy setting to set as the default for new packages. You can override this setting when uploading individual packages from the CLI or by connecting a plan file that declares a package as private. - - The difference between public and private packages is: - - - Anyone can find and use public packages. - - Only users with origin membership can find and use private packages. - -1. Select **Save and Continue** - - Habitat Builder does the following: - - - Creates your origin. - - Creates an [origin key pair]({{< relref "/habitat/origin_keys" >}}). - - Redirects Chef Habitat Builder to the origin page. - - ![Origin successfully created](/images/habitat/create-origin-done.png) diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/md/create_origins_cli.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/md/create_origins_cli.md deleted file mode 100644 index f97b95ce5f..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/md/create_origins_cli.md +++ /dev/null @@ -1,8 +0,0 @@ - -To create an origin with the hab CLI, use the [`hab origin create`]({{< relref "habitat_cli.md#hab-origin-create" >}}) command. For example: - -- ```bash - hab origin create - ``` - - Habitat creates an origin on the Chef Habitat Builder site. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/md/habitat_builder_overview.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/md/habitat_builder_overview.md deleted file mode 100644 index 7066282ad4..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/md/habitat_builder_overview.md +++ /dev/null @@ -1,4 +0,0 @@ -Chef Habitat Builder acts as the core of Chef's Application Delivery Enterprise hub. -It provides a repository for all available Chef Habitat packages built by Chef and the supporting community, as well as search and an API for clients. - -You can store application plans on the Chef Habitat Builder SaaS where the Chef Habitat community can view and access them. You can also deploy the [on-prem version of Chef Habitat Builder](https://github.com/habitat-sh/on-prem-builder) where you can store and maintain your apps in a secure environment. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/md/habitat_plans_overview.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/md/habitat_plans_overview.md deleted file mode 100644 index 314ea7db5a..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/md/habitat_plans_overview.md +++ /dev/null @@ -1,3 +0,0 @@ -A plan is the set of instructions, templates, and configuration files that define how you download, configure, make, install, and manage the lifecycle of the application artifact. The plan is defined in the `habitat` directory at the root of your project repository. - -The `habitat` directory includes a plan file (`plan.sh` for Linux systems or `plan.ps1` for Windows), a `default.toml` file, an optional `config` directory for configuration templates, and an optional `hooks` directory for lifecycle hooks. You can create this directory at the root of your application with `hab plan init`. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/md/habitat_services_overview.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/md/habitat_services_overview.md deleted file mode 100644 index a727af1c4c..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/md/habitat_services_overview.md +++ /dev/null @@ -1 +0,0 @@ -A service is a Chef Habitat package that is run and managed by a Supervisor. Services can be joined together into a [service group]({{< relref "/habitat/service_groups" >}}), which is a collection of services with the same package and topology type that are connected together across a Supervisor network. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/md/habitat_studio_overview.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/md/habitat_studio_overview.md deleted file mode 100644 index 657a278db0..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/md/habitat_studio_overview.md +++ /dev/null @@ -1 +0,0 @@ -The Chef Habitat Studio is a clean, self-contained, minimal environment in which you can develop, build, and package software that is free from any upstream operating system distribution. All tools and dependencies included in the Studio are installed through Chef Habitat packages, thus preventing any unwanted dependencies from being used by your package. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/md/habitat_supervisor_overview.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/md/habitat_supervisor_overview.md deleted file mode 100644 index 8c1e2fd7db..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/reusable/md/habitat_supervisor_overview.md +++ /dev/null @@ -1,6 +0,0 @@ -Chef Habitat Supervisor is a process manager that has two primary responsibilities: - -- A Supervisor runs your app's services. It starts, stops, updates, and monitors the services according to your plan. -- Supervisors can talk to each other. You can connect Supervisors together into a network and instruct them to send information to each other and take actions based on that information. - -In the Supervisor you can define topologies for you application, such as leader-follower or standalone, or more complex applications that include databases. The supervisor also allows you to inject tunables into your application. Allowing you to defer decisions about how your application behaves until runtime. \ No newline at end of file diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/running_habitat_linux_containers.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/running_habitat_linux_containers.md deleted file mode 100644 index 10f4db40d2..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/running_habitat_linux_containers.md +++ /dev/null @@ -1,103 +0,0 @@ -+++ -title = "Running Chef Habitat Linux Containers" -description = "Running Chef Habitat Linux Containers" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Running Chef Habitat Linux Containers" - identifier = "habitat/containers/running-habitat-linux-containers Linux Containers" - parent = "habitat/containers" - weight = 70 -+++ - -When you run `hab pkg export docker`, you'll get a Docker container that provides a few things. First, a minimal Linux OS filesystem is provided, with just enough configuration (e.g., `/etc/passwd`, `/etc/resolv.conf`, etc.) to run. Second, the contents of the exported Chef Habitat package, along with its complete dependency tree, as well as a complete Chef Habitat Supervisor installation, are provided, unpacked, in the `/hab/pkgs` directory. Finally, an entry-point script that will start the Supervisor, running the exported Chef Habitat package, is provided, allowing the container itself to behave as though it were the Supervisor. - -On Linux, the Chef Habitat Supervisor will normally run as the `root` user, and will start Chef Habitat services as the `pkg_svc_user` specified by that service. However, in some deployment scenarios, it undesirable--or even impossible--to run the Supervisor as `root`. The [OpenShift](https://www.openshift.com/) container platform, for instance, does not run containers as `root` by default, but as randomly-chosen anonymous user IDs. From version 0.53.0 onward, the Chef Habitat Supervisor can now run as an arbitrary user, providing users with more flexibility in how and where the use Chef Habitat. - -In order to support this in containers and provide maximal flexibility, the contents of the `/hab` directory are both readable _and writable_ by the `root` _group_. When specifying a user to run a container process as, the user's primary group will be reported as `root` if no matching group can be found in `/etc/group`. This will allow the user to create and populate the `/hab/sup` directory for managing Supervisor state, as well as the `/hab/svc` directory, which will contain all the service's state. This is in line with [recommendations from OpenShift](https://docs.openshift.com/container-platform/4.9/openshift_images/create-images.html#images-test-s21-using-openshift-for-building-the-image_create-images) on how to create containers that can run as a non-root user, but nothing in Chef Habitat's implementation is specific to OpenShift; indeed, all the examples provided below use pure Docker. - -## Caveats to Running as a Non-root User - -"There's no such thing as a free lunch", as the saying goes, and that holds true here. If the Supervisor is running as a non-root user, any processes that it supervises will be run as the same user; any values that the process might specify via `pkg_svc_user` and `pkg_svc_group` are essentially ignored. Furthermore, any files written out by the service during its operation are also owned by that same user. - -### Details - -Actually, the Supervisor does not care what user it is running as; rather, it uses Linux capabilities to guide its behavior. If the process has the `CAP_SETUID`, `CAP_SETGID`, and `CAP_CHOWN` capabilities, it will be able to run processes as the specified `pkg_svc_user` and `pkg_svc_group` (`CAP_CHOWN` is needed to ensure that the service processes can read and write files within the service's state directories). The Supervisor checks for the presence of these capabilities, and does not rely on having a user ID of 0 or the username `root`. - -## Container Deployment Scenarios - -### Running a Chef Habitat Container as a Root User - -This is the base case. If you are fine with running your container as `root`, you can do that directly: - -```sh -docker run --rm -it core/redis:latest -``` - -Here, `core/redis:latest` would be the image exported from the `core/redis` Chef Habitat package. The Supervisor will run as normal, with supervised processes running as the desired user. - -### Running a Chef Habitat Container as a Non-root User - -If you cannot run as the `root` user, but you are fine with `root` being the container user's primary group, you can simply specify a user ID to run as. This user need not exist in the container itself, and it's better if it doesn't. Using pure Docker, it might look like this: - -```sh -docker run --rm -it --user=888888 core/redis:latest -``` - -Again, we use our `core/redis` Chef Habitat package container; the user ID 888888 is simply a number chosen at random (this is how platforms like OpenShift operate). No user inside the container has this ID, meaning that the user will be an anonymous user with `root` as its primary group. Because of how we generate Chef Habitat containers, this fact ensures that the user has write permissions within the `/hab` directory. - -Due to the current logic around package installation, there is an extra step needed if you would like to have your containerized Supervisors update either themselves or the services they supervise. When installing packages as a non-root user, Chef Habitat will download the origin keys and compressed hart files into the user's `${HOME}/.hab` directory, rather than the global `/hab/cache` directory. You will need to ensure that a user-writable directory is mounted into the container, and specify it as the user's home directory using the `HOME` environment variable. Using pure Docker with a volume that is accessible by the user, that might look like this: - -```sh -docker volume create --driver local \\ - --opt type=tmpfs \\ - --opt device=tmpfs \\ - --opt o=size=100m,uid=888888 \\ - test_home - -docker run --rm -it \\ - --user=888888 \\ - --mount type=volume,src=test_home,dst=/myhome \\ - --env HOME=/myhome \\ - core/redis:latest --auto-update --strategy=at-once -``` - -This is merely an illustration; use whatever volume management approaches and service update strategies that are appropriate for your container scheduling system and your local deployment. - -As illustrated, updates of this kind are completely optional; you may prefer to move update responsibility to your container scheduler and treat your containers as immutable in this regard. - -## Running a Chef Habitat Container as a Non-root User in a Non-root Group - -If for whatever reason you do not want your user to be in the `root` group inside the container, you will need to add some additional volumes in order to create the needed directories. However, since you will (by definition) not have write permissions on the `/hab` directory as a whole, your Supervisor _will not_ be able to update either itself or the services it supervises. - -To implement this using pure Docker, you could do something like this (the group ID of `999999` was again chosen arbitrarily, as with the user ID): - -```sh -docker volume create --driver local \\ - --opt type=tmpfs \\ - --opt device=tmpfs \\ - --opt o=size=100m,uid=888888 \\ - sup_state - -docker volume create --driver local \\ - --opt type=tmpfs \\ - --opt device=tmpfs \\ - --opt o=size=100m,uid=888888 \\ - svc_state - -docker volume create --driver local \\ - --opt type=tmpfs \\ - --opt device=tmpfs \\ - --opt o=size=100m,uid=888888 \\ - launcher_state - -docker run --rm -it \\ - --user=888888:999999 \\ - --mount type=volume,src=sup_state,dst=/hab/sup \\ - --mount type=volume,src=svc_state,dst=/hab/svc \\ - --mount type=volume,src=launcher_state,dst=/hab/launcher \\ - core/redis:latest -``` - -Again, this is just an illustrative example; use the appropriate strategies for your specific circumstances. The key information here is to ensure that the `/hab/sup`, `/hab/svc`, and `/hab/launcher` directories are writable by the user inside the container. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/running_habitat_servers.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/running_habitat_servers.md deleted file mode 100644 index 921298f684..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/running_habitat_servers.md +++ /dev/null @@ -1,54 +0,0 @@ -+++ -title = "Running Chef Habitat on Servers (Linux and Windows)" -description = "Running Chef Habitat on Servers (Linux and Windows)" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Running Chef Habitat on Servers (Linux and Windows)" - identifier = "habitat/supervisors/running-habitat-servers" - parent = "habitat/supervisors" - weight = 25 -+++ - -Chef Habitat can be run on bare metal servers, as well as virtual machines. Currently, Chef Habitat can run on Linux and Windows platforms, and in all cases, running a Supervisor boils down to running `hab sup run`. How that happens depends on which platform you choose to use. - -## Running Chef Habitat on Linux - -First, you must [install Chef Habitat]({{< relref "install_habitat" >}}) itself on the machine. - -Second, many packages default to running as the `hab` user, so you should ensure that both a `hab` user and group exist: - -```bash -sudo groupadd hab -sudo useradd -g hab hab -``` - -Finally, you will need to wire Chef Habitat up to your systems init system. This may be SysVinit, systemd, runit, etc. The details will be different for each system, but in the end, you must call `hab sup run`. - -### Running under systemd - -A basic systemd unit file for Chef Habitat might look like this. This assumes that you have already created the `hab` user and group, as instructed above, and that your `hab` binary is linked to `/bin/hab`. - -```toml - [Unit] - Description=The Chef Habitat Supervisor - - [Service] - ExecStart=/bin/hab sup run - - [Install] - WantedBy=default.target -``` - -Depending on your needs and deployment, you will want to modify the options passed to `hab sup run`. In particular, if you wish to participate in larger Supervisor networks, you will need to pass at least one `--peer` option. - -## Running Chef Habitat on Windows - -As with Linux, you must first [install Chef Habitat]({{< relref "install_habitat" >}}) on the machine. Unlike Linux, however, the Windows Supervisor has no requirements for any `hab` user. - -On Windows, you can run the Supervisor as a Windows Service. You can use the `windows-service` Chef Habitat package to host the Supervisor inside the Windows Service Control Manager: - -```powershell -hab pkg install core/windows-service -``` diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/running_habitat_windows_containers.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/running_habitat_windows_containers.md deleted file mode 100644 index 69a435db46..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/running_habitat_windows_containers.md +++ /dev/null @@ -1,44 +0,0 @@ -+++ -title = "Running Chef Habitat Windows Containers" -description = "Running Chef Habitat Windows Containers" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Running Chef Habitat Windows Containers" - identifier = "habitat/containers/running-habitat-windows-containers Windows Containers" - parent = "habitat/containers" - weight = 80 -+++ - -Exported Windows images use `microsoft/windowsservercore` as their base. This is the equivalent of a minimal Windows Server 2016 Core install. So you should not expect non default features and roles to be enabled such as IIS or Active Directory. Consider using an `init` hook to install any features needed by your Chef Habitat service. - -## Container Pull and Startup Time - -The `microsoft/windowsservercore` image is approximately 5GB. Due to this large size, you can expect that the first time you run an exported Chef Habitat service, pulling down the image may take several minutes. This wait should only occur on the very first `docker run` of any Chef Habitat Windows service. Additionally, depending on the Windows host operating system, running the container may also take considerably longer than what one is accustomed to with Linux based containers. This startup time will be highly influenced by the container isolation mode described below. - -## Windows Containers and Host Kernel Isolation - -There are two types of Windows containers and each runs under a different level of kernel isolation. - -### Windows Server Containers - -These containers, like their Linux counterparts, share the host's kernel. You can expect these containers to start pretty quickly and this is the default container type on Windows Server 2016 hosts. - -### Hyper-V Containers - -Windows Hyper-V containers run inside of a very minimal Hyper-V VM. As a result, they do not share the host's kernel and offer a higher level of security and isolation. The cost of this isolation is that it will take longer for the container to start - perhaps a noticeable delay. Also be aware that the VM is provisioned with a default 1 GB limit of memory. If your service requires more than a gigabyte of memory, you can use the `--memory` argument with `docker run` and pass a larger limit. - -```bash -docker run --memory 2GB -it core/mysql -``` - -On a Windows 10 host, Windows containers will always run inside of Hyper-V isolation. Kernel sharing Windows Server containers are only available on Windows Server 2016 hosts. On Windows Server 2016, Windows Server containers are the default container type but you can force `docker run` to use Hyper-V containers by setting the `--isolation` argument to `hyperv`. - -```bash -docker run --isolation hyperv -it core/mysql -``` - -## Host Loopback Network - -A common container pattern is to forward the container port to a local port and then access the container application by accessing `localhost` on the forwarded port. With Windows containers, published ports cannot be accessed using `localhost`. You will instead need to use the IP address of the host or the IP of the individual container to access the application's endpoint. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/runtime_binding.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/runtime_binding.md deleted file mode 100644 index 6fb2459e3c..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/runtime_binding.md +++ /dev/null @@ -1,15 +0,0 @@ -+++ -title = "Runtime Services Group Binding" -description = "Runtime Services Group Binding" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Runtime Services Group Binding" - identifier = "habitat/diagrams/runtime-binding" - parent = "habitat/diagrams" - weight = 80 - -+++ - -![Chef Habitat Runtime Services Group Binding Diagram](/images/habitat/habitat-runtime-service-group-binding.png) diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/scaffolding.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/scaffolding.md deleted file mode 100644 index 0753f019d3..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/scaffolding.md +++ /dev/null @@ -1,50 +0,0 @@ -+++ -title = "Scaffolding" -description = "Scaffolding" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Scaffolding" - identifier = "habitat/plans/scaffolding" - parent = "habitat/plans" - weight = 95 -+++ - -Chef Habitat scaffoldings are standardized plans for automated building and running your application. Each scaffolding is tuned to the way your application was built, which allows it to create the appropriate [application lifecycle hooks]({{< relref "application_lifecycle_hooks" >}}) and add in the correct runtime dependencies when building the package for your application. Scaffoldings also provide some default health check hooks where appropriate to ensure your application is functioning reliably. Customized Scaffolding can be created to facilitate re-usability of common patterns in your organization for developing, building, and running your applications. - -## Automated Scaffolding - -While we are targeting many platforms for automated scaffolding we currently support Ruby, Node.js and Gradle. - -* [core/scaffolding-ruby](https://github.com/habitat-sh/core-plans/blob/main/scaffolding-ruby/doc/reference.md) -* [core/scaffolding-node](https://github.com/habitat-sh/core-plans/tree/main/scaffolding-node) -* [core/scaffolding-gradle](https://github.com/habitat-sh/core-plans/blob/main/scaffolding-gradle) - -## Variables - -Scaffolding provides certain customizable variables for language-specific behavior. Please see the appropriate scaffolding documentation for details. - -### Overriding Scaffolding Callbacks - -If you want to override phases of a scaffold's build in your plans, make sure to override the main `do_xxx` phase, not the callback directly. ex override `do_install()` instead of `do_default_install` or `do_node_install`. - -### Scaffolding Internals - -A language or framework scaffolding is shipped as a Chef Habitat package, which means that each scaffolding runtime dependency becomes a build dependency for the application being built. - -## lib/scaffolding.sh File - -To create scaffolding, a package must contain a `lib/scaffolding.sh` file which gets sourced by the build program running Bash. - -## scaffolding_load() Function - -A optional function named `scaffolding_load()` may be created in `lib/scaffolding.sh` which will be called early in the build program which allows a Scaffolding author to control and augment the `pkg_deps` and `pkg_build_deps` arrays. At this point, no other build or run dependencies have been resolved so the code in this function can only rely on what the build program provides or software pulled in via the Scaffolding's Plan. - -## Default Build Phases Implementations - -The remainder of the `lib/scaffolding.sh` contains one or more default implementations for the build phases. These include, but are not limited to: - -* `do_default_prepare()` -* `do_default_build()` -* `do_default_install()` diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/service_group_configuration.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/service_group_configuration.md deleted file mode 100644 index 83cc3ea91a..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/service_group_configuration.md +++ /dev/null @@ -1,68 +0,0 @@ -+++ -title = "Service Group Configuration" -description = "Update Services with File Uploads" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Service Group Configuration" - identifier = "habitat/services/Service Group Configuration" - parent = "habitat/services" - weight = 40 -+++ - -## Uploading Files to a Service Group - -In addition to [configuration updates]({{< relref "service_updates" >}}), you can -upload files to a service group. Keep these small - we recommend 4k or less per -file, and keep the count of files to a minimum. - -### Usage - -Use the [`hab file upload`]({{< relref "habitat_cli#hab-file-upload" >}}) command -to submit a file to a service group. Specify a peer in the ring to connect to, -the version number of the file, and the new path to the file itself. - -{{< note >}} -File updates for service groups must be versioned. The version number must be an -integer that starts at one and must be incremented with every subsequent update -to the same service group. - -If the version number is less than or equal to -the current version number, the change(s) will not be applied. -{{< /note >}} - -The following example shows how to upload a file to the ring: - -```bash -hab file upload myapp.prod 1 /tmp/yourfile.txt --remote-sup=hab1.mycompany.com -``` - -Your output would look something like this: - -``` -» Uploading file yourfile.txt to 1 incarnation myapp.prod -Ω Creating service file -↑ Applying via peer 172.0.0.3:9632 -★ Uploaded file -``` - -The services in the `myapp.prod` service group will receive the file, restarting if necessary: - -``` -hab-sup(MR): Receiving new version 1 of file secret.txt for myapp.prod -... -myapp.prod(SR): Service file updated, yourfile.txt -``` - -**Note**: Habitat will put the uplodaded file in your service's `svc/files` directory. - -### Encryption - -Files can be encrypted for the service group they are intended for. To do so, -pass the `--user` option with the name of your user key, and the `--org` option -with the organization of the service group. If you have the public key for the -service group, the data will be encrypted for that key, signed with your user key, -and sent to the ring. - -It will then be stored encrypted in memory, and decrypted on disk. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/service_group_topologies.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/service_group_topologies.md deleted file mode 100644 index 8aa08e9cce..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/service_group_topologies.md +++ /dev/null @@ -1,101 +0,0 @@ -+++ -title = "Service Group Topologies" -description = "Service Group Topologies" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Service Group Topologies" - identifier = "habitat/services/Service Group Topologies" - parent = "habitat/services" - weight = 30 -+++ - -A topology describes the intended relationship between peers within a service group. -Two topologies ship with Chef Habitat by default: **standalone** and **leader-follower**. -The leader-follower topology employs [leader election]({{< relref "sup_crypto" >}}) to define a leader. - -## Standalone - -The standalone topology is what a Supervisor starts with by default if no topology -is specified, or if the topology is explicitly specified with `--topology standalone` -when starting the Supervisor. The standalone topology means that the service group -members do not have any defined relationship with one another, other than sharing -the same configuration. - -## Leader-follower Topology - -In a leader-follower topology, one of the members of the service group is elected -the leader, and the other members of that service group become the followers of -that leader. This topology is common for database systems like MySQL or PostgreSQL, -where applications send writes to one member, and those writes are replicated to -one or more read replicas. - -As with any topology using leader election, you must start at least three peers -using the `--topology leader` flag to the Supervisor. - -```bash -hab sup run --topology leader --group production -hab svc load / -``` - -The first Supervisor will block until it has quorum. You would start additional -members by pointing them at the ring, using the `--peer` argument: - -```bash -hab sup run --topology leader --group production --peer 192.168.5.4 -hab svc load / -``` - -{{< note >}} - -The `--peer` service does not need a peer that is in the same service group; -it merely needs to be in the same ring with the other member(s). - -{{< /note >}} - -Once you have quorum, one member is elected a leader, the Supervisors in the service -group update the service's configuration in concordance with the policy defined -at package build time, and the service group starts up. - -### Defining Leader and Follower Behavior in Plans - -Chef Habitat allows you to use the same immutable package in different deployment -scenarios. In this example, a configuration template with conditional logic -will make the running application to behave differently based on whether -it is a leader or a follower: - -```handlebars -{{#if svc.me.follower}} - {{#with svc.leader as |leader|}} - replicaof {{leader.sys.ip}} {{leader.cfg.port}} - {{/with}} -{{/if}} -``` - -This logic says that if this peer is a follower, it will become a read replica of -the IP and port of service leader (`svc.leader`), which is found by service -discovery through the ring. However, if this peer is the leader, the entire list -of statements here evaluate to empty text -- meaning that the peer starts up as -the leader. - -## Robustness, Network Boundaries and Recovering from Partitions - -Within a leader-follower topology, it is possible to get into a partitioned state -where nodes are unable to achieve quorum. To solve this, use a permanent peer to -heal the netsplit. Pass the `--permanent-peer` option, or it's short form `-I`, -to make a Supervisor act as a permanent peer. - -```bash -hab sup run --topology leader --group production --permanent-peer -hab svc load / -``` - -When a Supervisor is instructed to act as a permanent peer, the other Supervisors -will attempt to connect with the permanent peer and achieve quorum -even if the permanent peer is confirmed to be dead. - -The notion of a permanent peer is an extension to the original -[SWIM](http://www.cs.cornell.edu/projects/Quicksilver/public_pdfs/SWIM.pdf) -gossip protocol. It can add robustness provided everyone has a permanent member -on both sides of the split. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/service_group_updates.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/service_group_updates.md deleted file mode 100644 index ec41c4d9be..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/service_group_updates.md +++ /dev/null @@ -1,67 +0,0 @@ -+++ -title = "Service Group Updates" -description = "Update service groups with supervisor configuration" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Service Group Updates" - identifier = "habitat/services/Service Group Updates" - parent = "habitat/services" - weight = 50 -+++ - -The Chef Habitat Supervisor can be configured to leverage an optional _update strategy_, -which describes how the Supervisor and its peers within a service group should -respond when a new version of a package is available. - -To use an update strategy, configure the Supervisor to subscribe to Chef Habitat -Builder, and more specifically, a channel for new versions. - -## Configuring an Update Strategy - -Chef Habitat supports three update strategies: `none`, `rolling`, and `at-once`. - -To start a Supervisor with the auto-update strategy, pass the `--strategy` argument -to a Supervisor run command, and optionally specify the depot URL: - -```bash -hab sup run --strategy rolling --url https://bldr.habitat.sh -hab svc load / -``` - -### None Strategy - -This strategy means your package will not automatically be updated when a newer -version is available. By default, Supervisors start with their update strategy -set to `none` unless explicitly set to one of the other two update strategies. - -### Rolling Strategy - -This strategy requires Supervisors to update to a newer version of their package -one at a time in their service group. An update leader is elected which all Supervisors -within a service group will update around. All update followers will first ensure -they are running the same version of a service that their leader is running, and -then the leader will poll Builder for a newer version of the service's package. - -Once the update leader finds a new version, it will update and wait until all other -alive members in the service group have also been updated before once again attempting -to find a newer version of software to update to. Updates will happen more or less -one at a time until completion with the exception of a new node being introduced into the service -group during the middle of an update. - -If your service group is also running with the `--topology leader` flag, the leader -of that election will never become the update leader, so all followers within a leader -topology will update first. - -It's important to note that because we must perform a leader election to determine -an update leader, *you must have at least 3 Supervisors running a service group -to take advantage of the rolling update strategy*. - -### At-Once Strategy - -This strategy does no peer coordination with other Supervisors in the service group; -it merely updates the underlying Chef Habitat package whenever it detects that a -new version has either been published to a depot or installed to the local Chef -Habitat `pkg` cache. No coordination between Supervisors is done, each Supervisor -will poll Builder on their own. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/service_groups.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/service_groups.md deleted file mode 100644 index d35be93ad7..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/service_groups.md +++ /dev/null @@ -1,90 +0,0 @@ -+++ -title = "Service Groups" -description = "Service Groups" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Service Groups" - identifier = "habitat/services/Service Groups" - parent = "habitat/services" - weight = 20 -+++ - -A service group is a logical grouping of services with the same package and topology type connected together across a Supervisor network. -They are created to share configuration and file updates among the services within those groups and can be segmented based on workflow or deployment needs (QA, Production, and so on). -Updates can also be [encrypted]({{< relref "sup_secure" >}}) so that only members of a specific service group can decrypt the contents. - -By default, every service joins the `service-name.default` service group unless -otherwise specified at runtime. - -In addition, multiple service groups can reside in the same Supervisor network. -This allows data exposed by Supervisors to be shared with other members of the -ring, regardless of which group they are in. - -## Joining a Service Group - -To join services together in a group, they must be running on Supervisors that -are participating in the same Supervisor gossip network (i.e., they are ultimately -peered together), and they must be using the same group name. To illustrate, we'll -show two `core/redis` services joining into the same group. - -First, we'll start up two Supervisors on different hosts, peering the second one -back to the first. - -```bash -$ hab sup run # on 172.18.0.2 (Supervisor A) -hab-sup(MR): Supervisor Member-ID e89b6616d2c040c8a82f475b00ba8c69 -hab-sup(MR): Starting gossip-listener on 0.0.0.0:9638 -hab-sup(MR): Starting ctl-gateway on 0.0.0.0:9632 -hab-sup(MR): Starting http-gateway on 0.0.0.0:9631 -``` - -```bash -$ hab sup run --peer=172.18.0.2:9638 # on 172.18.0.3 (Supervisor B) -hab-sup(MR): Supervisor Member-ID bc8dc23243e44fee8ea7b9023073c28a -hab-sup(MR): Starting gossip-listener on 0.0.0.0:9638 -hab-sup(MR): Starting ctl-gateway on 0.0.0.0:9632 -hab-sup(MR): Starting http-gateway on 0.0.0.0:9631 -``` - -Now, run the following on each Supervisor to load `core/redis` in the "prod" group: - -``` -hab svc load core/redis --group=prod -``` - -Each will start up, and will be joined into the same group; here is Supervisor A's output: -![Supervisor A running Redis](/images/habitat/supervisor_a_before.png) - -And here is Supervisor B's output: -![Supervisor B running Redis](/images/habitat/supervisor_b_before.png) - -Note that they are both listening on the same port. - -To prove they are in the same group, we can apply a configuration change; if they -are in the same group, they should both receive the change. - -Let's change the port they're running on using the `hab config apply` command, run from Supervisor A. - -```bash -echo 'port = 2112' | hab config apply redis.prod 1 -``` - -Both service instances restart with the new configuration. Supervisor A's output is: - -![Supervisor A running Redis on a new port](/images/habitat/supervisor_a_after.png) - -and Supervisor B's output is: - -![Supervisor B running Redis on a new port](/images/habitat/supervisor_b_after.png) - -Note that they have both restarted (as evidenced by the new PID values), and that -both are now running on port 2112, as we instructed. - -Had the services been in different groups, the configuration change would not have -applied to both of them (it was targeted at `redis.prod`). If the Supervisors has -not been in gossip communication (achieved here through the use of the `--peer` -option when Supervisor B was started), the configuration rumor (injected into -Supervisor A's gossip network) would not have made it to `core/redis` service running -on Supervisor B. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/service_restarts.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/service_restarts.md deleted file mode 100644 index 90606c1588..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/service_restarts.md +++ /dev/null @@ -1,95 +0,0 @@ -+++ -title = "Service Restarts" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Service Restarts" - identifier = "habitat/reference/service-restarts Service Restarts" - parent = "habitat/reference" -+++ - -Starting with Chef Habitat 1.6.491, you can configure a service restart backoff period to control how quickly a service is restarted following the failure of an init or run hook. Before this release, if there was a failure of the init or run hook, the supervisor would attempt to restart the service immediately, potentially leading to excessive load on external APIs similar to a denial-of-service attack. - -## Overview - -The restart backoff behavior is set by three parameters: - -- The minimum backoff period sets the minimum duration in seconds to wait before restarting a service. -- The maximum backoff period sets the maximum duration in seconds to wait before restarting a service. -- The restart cooldown period sets the time in seconds to wait before resetting the current backoff duration to the minimum backoff period. - -{{< note >}} - -The restart cooldown period is important because it ensures that the supervisor handles potential failures during restart correctly. -If the cooldown period is not long enough, a slow service may still be restarting after the cooldown period has passed. -If a service fails during a restart in that scenario, the service will not backoff correctly before the following restart. -We recommend setting the restart cooldown period to be at least double your expected startup time to be safe. - -{{< /note >}} - -Enable these values using the [`sup run`]({{< relref "habitat_cli#hab-sup" >}}) command by passing in the number of seconds to the following parameters: - -- `service-min-backoff-period` -- `service-max-backoff-period` -- `service-restart-cooldown-period` - -For example: - -```bash -hab sup run --service-min-backoff-period 5 --service-max-backoff-period 20 --service-restart-cooldown-period 60 core/redis -``` - -You can also set this behavior using these parameters in the [supervisor configuration file]({{< relref "sup_config" >}}): - -- `service_min_backoff_period` -- `service_max_backoff_period` -- `service_restart_cooldown_period`. - -Chef Habitat uses a decorrelated jitter algorithm to determine the backoff period. See [this blog post](https://aws.amazon.com/blogs/architecture/exponential-backoff-and-jitter/) for a more in-depth comparison of various backoff algorithms and their efficiency. - -{{< note >}} -There is no way to change the backoff algorithm. However, if you wish to have a simple fixed backoff, set the `service-min-backoff-period` and `service-max-backoff-period` to the same time in seconds. -{{< /note >}} - -## Service Failure Detection - -Adding restart backoff behavior requires the ability to detect when a service has successfully started to reset the backoff period. -Unfortunately, there is no clean way to differentiate between a service failure and a service simply taking too long to startup. A health-check hook would enable the detection of successful service startups; however, if a health check is absent, there is no way to know if the service started up. There may also be cases where the initial health check succeeds, but the service goes down shortly afterward. - -We attempt to solve this problem by using a restart cooldown period. The cooldown period is a continuous duration of time without a restart, after which we assume a service has started up successfully. It is important to configure this correctly to ensure the backoff period does not get reset prematurely. -We recommend setting the `service-restart-cooldown-period` to be at least double your expected startup time to be safe. In general, a longer cooldown will not have an adverse effect; however, a shorter one may prevent the backoff behavior completely. - -See the examples below to more properly understand this. - -## Examples - -**Slow service with an _incorrect_ configuration** - -```bash -hab sup run --service-min-backoff-period 5 --service-max-backoff-period 20 --service-restart-cooldown-period 10 ORG_NAME/SERVICE_NAME -``` - -In the event of a failure during startup with the above configuration, the service will continue to restart after 5 seconds because the service crashes again after the short restart cooldown period has passed, potentially leading to excessive load on external APIs: - -1. T = 0, service starts up -1. T = 30, service crashes, will be restarted after 5 secs -1. T = 35, service is restarted -1. T = 45, service backoff period is reset to 5 secs because 10 secs has elapsed since the last restart -1. T = 65, service crashes again, it will now be restarted after 5 secs due to the backoff period resetting at T=45 -1. T = 70, service is restarted again - -**Slow service with a _correct_ configuration** - -```bash -hab sup run --service-min-backoff-period 5 --service-max-backoff-period 20 --service-restart-cooldown-period 60 ORG_NAME/SERVICE_NAME -``` - -In the event of a failure during startup with the above configuration, the service will restart at a random time (15 seconds in this example) which would reduce the load on external APIs: - -1. T = 0, service starts up -1. T = 30, service crashes, will be restarted after 5 secs -1. T = 35, service is restarted -1. T = 65, service crashes again, it will restart after a random duration between 5 and 20 secs, let's assume 15. -1. T = 80, service is restarted again, notice that the backoff period has not been reset. -1. T = 140, service backoff period is reset to 5 secs because 60 secs has elapsed since the last restart diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/service_updates.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/service_updates.md deleted file mode 100644 index 1e8b0d32d0..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/service_updates.md +++ /dev/null @@ -1,119 +0,0 @@ -+++ -title = "Single Service Updates" -description = "Update single services at runtime or dynamically" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Single Service Updates" - identifier = "habitat/services/service-updates Individual Configuration Updates" - parent = "habitat/services" - weight = 40 -+++ - -One of the key features of Chef Habitat is the ability to define an immutable package with a default configuration which can then be updated dynamically at runtime. You can update service configuration on two levels: individual services (for testing purposes), or a service group. - -## Apply Configuration Updates to an Individual Service - -When starting a single service, you can provide alternate configuration values to those specified in `default.toml`. - -### Using a _user.toml_ File - -You can supply a `user.toml` containing any configuration data that you want to override default values. This file should be placed in the Chef Habitat `user` directory under the `config` subdirectory of the specific service directory that owns the configuration data. For example, to override the default configuration of the `myservice` service, this `user.toml` would be located at `/hab/user/myservice/config/user.toml`. - -### Using an Environment Variable - -Override default configuration data through the use of an environment variable with the following format: - -```bash -HAB_PACKAGENAME='{"keyname1":"newvalue1", "tablename1":{"keyname2":"newvalue2"}}' -``` - -```bash -HAB_MYTUTORIALAPP='{"message":"Chef Habitat rocks!"}' hab run / -``` - -{{< note >}} -The syntax used for applying configuration through environment variables can be either JSON or TOML, but TOML is preferred. The package name in the environment variable must be uppercase, any dashes must be replaced with underscores. -{{< /note >}} - -{{< note >}} -Variables must be set when the Supervisor process starts, not when the service is loaded, which may require a bit of planning on the part of the Chef Habitat user. -{{< /note >}} - -For multiline environment variables, such as those in a TOML table or nested key value pairs, it can be easier to place your changes in a file and pass the file in. For example: - -```bash -HAB_MYTUTORIALAPP="$(cat my-env-stuff.toml)" hab run -hab svc load /mytutorialapp -``` - -Or, for [testing scenarios and containerized workflows]({{< relref "sup_run/#starting-the-supervisor" >}}): - -```bash -HAB_MYTUTORIALAPP="$(cat my-env-stuff.toml)" hab run /mytutorialapp -``` - -The main advantage of applying configuration updates to an individual service through an environment variable is that you can quickly test configuration settings to see how your service behaves at runtime. The disadvantages of this method are that configuration changes have to be applied when the Supervisor itself starts up, and you have to restart a running Supervisor (and thus, all services it may be running) in order to change these settings again. - -## Apply Configuration Updates to all Services in a Service Group - -Similar to specifying updates to individual settings at runtime, you can apply multiple configuration changes to an entire service group at runtime. These configuration updates can be sent in the clear or encrypted in gossip messages through [wire encryption]({{< relref "sup_secure" >}}). Configuration updates to a service group will trigger a restart of the services as new changes are applied throughout the group. - -### Usage - -When submitting a configuration update to a service group, you must specify the following: - -- a Supervisor to connect to -- the version number of the configuration update -- the new configuration - -Configuration updates can be either TOML passed into stdin, or passed in a TOML -file that is referenced in [`hab config apply`]({{< relref "habitat_cli#hab-config-apply" >}}). - -{{< note >}} -Configuration updates for service groups must be versioned. The version number must be an integer that starts at one and must be incremented with every subsequent update to the same service group. *If the version number is less than or equal to the current version number, the change(s) will not be applied.* -{{< /note >}} - -Here are some examples of how to apply configuration changes through both the shell and through a TOML file. - -**Stdin** - -```bash -echo 'buffersize = 16384' | hab config apply --remote-sup=hab1.mycompany.com myapp.prod 1 -``` - -**TOML file** - -```bash -hab config apply --remote-sup=hab1.mycompany.com myapp.prod 1 /tmp/newconfig.toml -``` - -Your output would look something like this: - -```bash -» Setting new configuration version 1 for myapp.prod -Ω Creating service configuration -↑ Applying via peer 172.18.0.2:9632 -★ Applied configuration -``` - -The services in the myapp.prod service group will restart. - -```bash -myapp.prod(SR): Service configuration updated from butterfly: acd2c21580748d38f64a014f964f19a0c1547955e4c86e63bf641a4e142b2200 -hab-sup(SC): Updated myapp.conf a85c2ed271620f895abd3f8065f265e41f198973317cc548a016f3eb60c7e13c -myapp.prod(SV): Stopping -... -myapp.prod(SV): Starting -``` - -{{< note >}} -As with all Supervisor interaction commands, if you do not specify `--remote-sup`, `hab config apply` will attempt to connect to a Supervisor running on the same host. -{{< /note >}} - -### Encryption - -Configuration updates can be encrypted for the service group they are intended. To do so, pass the `--user` option with the name of your user key, and the `--org` option with the organization of the service group. If you have the public key for the service group, the data will be encrypted for that key, signed with your user key, and sent to the ring. - -It will then be stored encrypted in memory, and decrypted on disk. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/studio.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/studio.md deleted file mode 100644 index 4ab1d3f9a4..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/studio.md +++ /dev/null @@ -1,111 +0,0 @@ -+++ -title = "Chef Habitat Studio Overview" -description = "About the Chef Habitat Studio" -draft = false -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Habitat Studio" - identifier = "habitat/studio Habitat Studio" - parent = "habitat" - weight = 80 - -+++ - - - -{{< readfile file="content/habitat/reusable/md/habitat_studio_overview.md" >}} - -## Customizing Studio - -When you enter a Studio, Chef Habitat will attempt to locate `/src/.studiorc` on Linux or `/src/studio_profile.ps1` on Windows and source it. -Think `~/.bashrc` or `$PROFILE`. -This file can be used to export any environment variables like the ones in `/reference/environment-variables`, as well as any other shell customizations to help you develop your plans from within the Studio. - -To use this feature, place a `.studiorc` (Linux) or `studio_profile.ps1` (Windows) in the current working directory -where you will run `hab studio enter`. - -{{< note >}} - -Chef Habitat will only source `.studiorc` or `studio_profile.ps1` when you run `hab studio enter`--it will not be sourced when calling `hab studio run`, `hab studio build`, or `hab pkg build`. - -{{< /note >}} - -### Why do we need it (Linux) - -The primary purpose of the Studio on Linux is to provide environmental and filesystem isolation from the build host during the build process. Many common environmental variables can influence the build process, such as PATH putting user installed tools ahead of the desired tool versions. Filesystem isolation is important as many tools use common system paths to autodiscover libraries, putting them ahead of the desired Habitat libraries. The result is a known, minimal environment that is portable and consistent across hosts (laptop to build farm) and forces the users to be explicit about how they build and package their software - -### Why do we need it (Windows) - -The purpose of the Studio on Windows is fundamentally the same as Linux. However, Windows cannot achieve filesystem isolation with the "native" studio in the same way that Linux can, but this is also less important in Windows. It does provide similar environmental isolation, though there are unique constraints imposed by Windows that require certain system paths to be available. For instance, removing the system32 libraries and tools would be unnatural at best and completely break Windows at worst, but the Studio will strip all other PATH entries (your ProgramFiles applications for example) in order to provide a more isolated environment. Registry isolation is also a concern that is different from Linux, but the native studio does not provide this isolation. Note that the Docker Windows Studio mentioned below provides much more thorough isolation. - -One other purpose of the Studio on Windows is to provide a known and common Powershell environment that the Habitat build program is compatible with. The Windows Studio includes a packaged version of Powershell which is different from the version of Powershell that ships on the OS. Entering an interactive Windows Studio makes it easier to troubleshoot builds because one is placed in the same version of Powershell that builds their packages and also the same version used by the Habitat Supervisor at runtime. - -## What kinds of studios are there? - -The Studio as an abstract concept is an environment to provide the required guarantees for builds. The `hab studio` command is our interface to do the requisite setup before handing control over to a studio implementation. `pkg build` uses the same setup but instead of creating an interactive process, it invokes `build` directly in a non-interactive environment. - -There are currently four implementations of the studio provided by the Habitat team. The studio implementations build upon common utilities, such as chroot or Docker containers, thus constraints on the studio behaviors, where it can run, what kinds of packages it can build, and in many cases what kinds of errors you can expect, are imposed by those tools. In the case of errors, it's often a case of understanding and troubleshooting the underlying tool used to implement the studio rather than troubleshooting the studio itself. - -### Linux "native" - aka `core/hab-studio` - -Built using chroot and bind mounts to provide access to required paths from the host. This is the default studio on Linux, and only functions on Linux based systems. This requires root privileges to invoke, and the `hab studio` command will attempt to use `sudo` to elevate the users privileges, if they are not already root. In addition, the installation of this package requires root privileges, as `/hab/pkgs` is owned by the root user. Specifically, chroot requires CAP_SYS_CHROOT and mounts require CAP_SYS_ADMIN. In addition to the bind mounts, `/proc` is required to be mounted for builds to function. - -### Linux "Docker Studio" - -The Linux Docker Studio is a completely separate implementation from the native studio, sharing no code aside from the common `hab studio` entrypoint. This difference in implementation includes available subcommands and help documentation, often leading to confusion. `hab studio -D` provides the necessary conversion to the required Docker CLI arguments, such as mounting volumes from the host into the container and setting the image to run. You can invoke this studio using only Docker commands, but requires additional effort in setting all the correct options. - -This studio was built to not require elevated permissions to run, to be able to provide studio builds inside CI systems or orchestration engines such as Kubernetes where elevated privileges are typically verboten. However, you still need to be able to communicate with the container engine in order to start the container. - -### Windows "native" - aka `core/hab-studio` - -The Windows studio uses Junction mounts in order to provide a consistent filesystem view in order to provide a similar experience to the Linux studios. Windows has no concept of "chroot" or jailed filesystems, so it provides no isolation from the host paths, registry and other machine scoped APIs (like Windows features, etc.). - -### Windows "Docker Studio" - -The Windows Docker studio does not exist as a component like `core/hab-studio` or `rootless_studio` in the Habitat code base. Instead it is created in our release pipeline, using a minimal Windows Container as the base and layering in the Windows implementation of `core/hab-studio` to build a Docker image. Like the rootless studio, this can be invoked using only the Docker CLI with the same additional setup required to set the correct options. - -## Studio platform support - -There are 4 implementations of the studio, and three primary supported operating systems that the `hab studio` can be invoked from. This matrix shows which studios can be run on the various operating systems. - -| Studio | Linux | macOS | Windows | -|--------|-------|-------|---------| -| Linux Native | Yes | No | No | -| Linux Docker | Yes | Yes | Yes | -| Windows Native | No | No | Yes | -| Windows Docker | No | No | Yes | - -### Why do we need privileged containers to build (on Linux)? - -Users wishing to build Habitat packages in containers will typically have their CI agent invoke `hab pkg build*`. This agent will be running in a non-privileged container, or possibly create a non-privileged container to invoke `hab pkg build`. - -At this point, the hab command will try to create the studio to run the command in. In the case of the native studio, this will fail because the container it is running in does not have the `CAP_SYS_CHROOT` or `CAP_SYS_ADMIN` capabilities. The Docker studio will also fail, as the environment the build is executing in won't have permissions to run containers, and also wouldn't have access to the Docker socket (or Docker in Docker). - -It's possible that if the users are able to provide credentials to access a remote Docker host, we would be able to build, though in secured environments this is probably unlikely. I also don't know if volume mapping can work across the network. Even if it is possible, any IO operations, such as reading the source would be slow. - -We also want to be careful about exposing build functionality directly to CI agents without requiring the studio boundary. We'd likely start (for example) fielding support questions around our package quality from user software segfaulting, when the underlying issue was the package was built on an Ubuntu host and it linked against the wrong libraries. - -Today, users can configure their agents to run the Docker studio image directly, but that requires them to perform all the set up `hab pkg build` would normally do for them, creating a point of friction. - -## Building packages cross platform - -One question often posed is the desire to build Windows packages on non-Windows systems. This is often spurred by the ability to build Linux packages on Windows or macOS. However, this is not a capability provided by the Studio, but by Docker. Docker runs a minimal Linux VM (using Hyper-V on Windows and Hyperkit on macOS) to provide the ability to run Linux containers. - -### The "Mac Studio" - -There is no Spoon. The Studio on macOS relies on the Docker Desktop creating and running a Docker host inside a headless virtual machine. This gives us the capability to develop and build Linux packages on macOS. macOS itself provides no os-virtualization primitives beyond chroot. Because `hab studio` manages the set up and execution of the Docker CLI command, this gives the illusion that we are providing some magic to build Linux packages on Mac. - -### How the Studio is used - -Studios are used in interactive modes to develop packages, but are often used interactively to also build the resulting packages. While this is fine, any time you are invoking a build from an interactive process that has had additional commands run before the build start, such as creating binlinks or even invoking other builds, you run the risk of creating a "tainted" build. In other words you lose some of the guarantees provided by the studio, leading to scenarios where builds between developers or CI are different. - -Studios are also used to develop software, though this is a less than ideal experience today as it requires additional setup from the user. This is because traditional developer tools have assumptions about the environment they are operating in and have no knowledge of the Habitat package structure. This is a point of friction to enable developers to develop against the same set of libraries that their software will ultimately be deployed against, allowing us to further "shift left". diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup.md deleted file mode 100644 index 590799bcfb..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup.md +++ /dev/null @@ -1,37 +0,0 @@ -+++ -title = "Chef Habitat Supervisor" -aliases = ["/habitat/best-practices/"] -date = 2020-10-26T18:47:18-07:00 -draft = false -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "About Supervisors" - identifier = "habitat/supervisors/sup Supervisors" - parent = "habitat/supervisors" - weight = 10 -+++ - -The Supervisor is a process manager that has two primary responsibilities. First, it starts and monitors child services defined in the plan it is running. Second, it receives and acts upon information from the other Supervisors to which it is connected. A service will be reconfigured through application lifecycle hooks if its configuration has changed. - -## The Supervisor Ring - -Supervisors typically run in a network, which we refer to as a *ring* (although it is more like a peer-to-peer network rather than a circular ring). The ring can be very large; it could contain hundreds or thousands of supervisors. The membership list of this ring is maintained independently by each Supervisor and is known as the *census*. - -## Census - -The census is the core of the service discovery mechanism in Chef Habitat. It keeps track of every Supervisor in the ring, and handles reading, writing, and serializing it with the discovery backend. - -Each Supervisor in the system is a *census entry* that together form a *census*. Operations to discover or mutate the state of the census happen through algorithms that arrive at the same conclusion given the same inputs. - -An example is leader election: it's handled here by having a consistent (and simple) algorithm for selecting a leader deterministically for the group. We rely on the eventual consistency of every Supervisor's census entry to elect a new leader in a reasonable amount of time. - -## Supervisor REST API - -The Chef Habitat Supervisor provides a HTTP API to expose cluster metadata, statistics, and general diagnostic information useful for monitoring and support in the form of a JSON document. It also provides detailed information about the Chef Habitat package that it is supervising, including metadata such as the build and runtime dependencies and their versions. - -## Control Gateway - -The Supervisor control gateway is used to issue commands to a remote Supervisor. When a new Supervisor is created, a key for the `HAB_CTL_SECRET` environment variable is generated for it by default, if one is not already present; this key is used to authenticate requests that are made via the control gateway. -See the [control gateway]({{< relref "keys#control-gateway" >}}) documentation for more details. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_config.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_config.md deleted file mode 100644 index 99b68b7895..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_config.md +++ /dev/null @@ -1,211 +0,0 @@ -+++ -title = "Supervisor Configuration File" -description = "Service Change Rollback" -date = 2020-10-26T17:32:36-07:00 -draft = false -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Supervisor Configuration File" - identifier = "habitat/supervisors/sup_config How to Rollback" - parent = "habitat/supervisors" - weight = 85 -+++ - -Generate a Supervisor configuration file and use it to set any of the 40+ Supervisor configuration settings instead of configuring them on the command line. - -
- -
- -Chef Habitat looks for Supervisor configuration settings in four locations and applies them in order, which means that settings defined in later locations overwrite earlier ones. - -```bash -hab sup run --generate-config -``` - -```bash -hab sup run --generate-config > config.toml -``` - -The Supervisor settings look-up order: - -1. The fixed config file location `/hab/sup/default/config/sup.toml` on the Supervisor -2. Files passed with the command, `hab sup run --config-files /config/file1.toml /config/file2.toml`, where - * You can pass more than one file command - * The settings in the later files overwrite those from the earlier, which means that for the same settings specified in both files in the command `hab sup run --config-files /config/file1.toml /config/file2.toml`, you will end up with the settings from `file2.toml` applied to the Supervisor -3. From [environment variables]({{< relref "environment_variables" >}}), if they exist -4. From settings passed from the [`hab sup run` command]({{< relref "habitat_cli/#hab-sup-run" >}}) - -```toml config.toml -### The listen address for the Gossip Gateway -listen_gossip = "0.0.0.0:9638" - -### Start the supervisor in local mode -local_gossip_mode = false - -### The listen address for the HTTP Gateway -listen_http = "0.0.0.0:9631" - -### Disable the HTTP Gateway completely -http_disable = false - -### The listen address for the Control Gateway -listen_ctl = "127.0.0.1:9632" - -### The organization the Supervisor and its services are part of -organization = "my-org" - -### The listen address of one or more initial peers (IP[:PORT]) -peer = ["1.1.1.1:9632", "2.2.2.2:9632", "3.3.3.3:9632"] - -### Make this Supervisor a permanent peer -permanent_peer = false - -### Watch this file for connecting to the ring -peer_watch_file = "/path/to/file" - -### Cache for creating and searching for encryption keys -cache_key_path = "/path/to/file" - -### The name of the ring used by the Supervisor when running with wire encryption -ring = "my-ring" - -### Use the package config from this path rather than the package itself -config_from = "/path/to/file" - -### Enable automatic updates for the Supervisor itself -auto_update = false - -### The private key for HTTP Gateway TLS encryption -### -### Read the private key from KEY_FILE. This should be an RSA private key or PKCS8-encoded private key in PEM format. -key_file = "/path/to/file" - -### The server certificates for HTTP Gateway TLS encryption -### -### Read server certificates from CERT_FILE. This should contain PEM-format certificates in the right order. The first certificate should certify KEY_FILE. The last should be a root CA. -cert_file = "/path/to/file" - -### The CA certificate for HTTP Gateway TLS encryption -### -### Read the CA certificate from CA_CERT_FILE. This should contain PEM-format certificate that can be used to validate client requests -ca_cert_file = "/path/to/file" - -### Load a Habitat package as part of the Supervisor startup -### -### The package can be specified by a package identifier (ex: core/redis) or filepath to a Habitat artifact (ex: /home/core-redis-3.0.7-21120102031201-x86_64-linux.hart). -pkg_ident_or_artifact = "core/redis" - -### Verbose output showing file and line/column numbers -verbose = false - -### Turn ANSI color off -no_color = false - -### Use structured JSON logging for the Supervisor -### -### This option also sets NO_COLOR. -json_logging = false - -### The IPv4 address to use as the `sys.ip` template variable -### -### If this argument is not set, the supervisor tries to dynamically determine an IP address. If that fails, the supervisor defaults to using `127.0.0.1`. -sys_ip_address = "1.2.3.4" - -### The name of the application for event stream purposes -### -### This will be attached to all events generated by this Supervisor. -event_stream_application = "my-app" - -### The name of the environment for event stream purposes -### -### This will be attached to all events generated by this Supervisor. -event_stream_environment = "my-env" - -### Event stream connection timeout before exiting the Supervisor -### -### Set to '0' to immediately start the Supervisor and continue running regardless of the initial connection status. -event_stream_connect_timeout = 60 - -### The event stream connection url used to send events to Chef Automate -### -### This enables the event stream and requires EVENT_STREAM_APPLICATION, EVENT_STREAM_ENVIRONMENT, and EVENT_STREAM_TOKEN also be set. -event_stream_url = "nats://127.0.0.1:4222" - -### The name of the site where this Supervisor is running for event stream purposes -event_stream_site = "my-site" - -### The authentication token for connecting the event stream to Chef Automate -event_stream_token = "my-token" - -### An arbitrary key-value pair to add to each event generated by this Supervisor -event_meta = ["my-key1=my-val1", "my-key2=my-val2", "abc=123"] - -### The path to Chef Automate's event stream certificate used to establish a TLS connection -### -### The certificate should be in PEM format. -event_stream_server_certificate = "/path/to/file" - -### Automatically cleanup old packages -### -### The Supervisor will automatically cleanup old packages only keeping the KEEP_LATEST_PACKAGES latest packages. If this argument is not specified, no automatic package cleanup is performed. -keep_latest_packages = 1 - -### Receive updates from the specified release channel -channel = "my-channel" - -### Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) -bldr_url = "https://my-bldr.url" - -### The service group with shared config and topology -group = "my-group" - -### Service topology -topology = "leader" - -### The update strategy -strategy = "at-once" - -### The condition dictating when this service should update -### -### latest: Runs the latest package that can be found in the configured channel and local packages. -### -### track-channel: Always run what is at the head of a given channel. This enables service rollback where demoting a package from a channel will cause the package to rollback to an older version of the package. A ramification of enabling this condition is packages newer than the package at the head of the channel will be automatically uninstalled during a service rollback. -update_condition = "track-channel" - -### The minimum duration in seconds to wait before restarting a service due to a init / run hook failure. -### -### The default value if this config is absent is 0 seconds to preserve legacy supervisor behavior. -service_min_backoff_period = 10 - -### The maximum duration in seconds to wait before restarting a service due to init / run hook failure. -### -### The default value if this config is absent is 0 seconds to preserve legacy supervisor behavior. -service_max_backoff_period = 180 - -### The duration of time in seconds to wait before resetting the current backoff duration to the 'service_min_backoff_period'. -### This is important because it ensures that the supervisor handles potential failures during restart correctly. -### If the cooldown period is not long enough, a slow service may still be restarting after the cooldown period has passed. -### If a service fails during restart but after the cooldown period has passed, the service will not backoff correctly before the following restart. -### -### The default value if this config is absent is 300 seconds. -service_restart_cooldown_period = 300 - -### One or more service groups to bind to a configuration -bind = ["port:redis.default"] - -### Governs how the presence or absence of binds affects service startup -### -### strict: blocks startup until all binds are present. -binding_mode = "strict" - -### The interval in seconds on which to run health checks -health_check_interval = 60 - -### The delay in seconds after sending the shutdown signal to wait before killing the service process -### -### The default value can be set in the packages plan file. -shutdown_timeout = 10 -``` diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_crypto.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_crypto.md deleted file mode 100644 index e171a7b392..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_crypto.md +++ /dev/null @@ -1,49 +0,0 @@ -+++ -title = "Supervisor Cryptography" -date = 2020-10-26T19:09:25-07:00 -draft = false -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Supervisor Cryptography" - identifier = "habitat/supervisors/Supervisor Cryptography" - parent = "habitat/supervisors" - weight = 70 -+++ - -Chef Habitat implements cryptography using a Rust [implementation](https://github.com/jedisct1/libsodium) of [NaCl](https://nacl.cr.yp.to/) called `libsodium`. `libsodium` provides a fast, modern framework for encryption, decryption, signing, and verification. - -Chef Habitat uses both symmetric encryption (for wire encryption) and asymmetric encryption (for everything else). If you are not familiar with the difference between the two, please consult [this article](https://support.microsoft.com/en-us/topic/a082a391-dee8-6265-9ce6-77c7f07c48dd). - -### Message Encryption - -When you have either wire encryption or service group encryption turned on, the messages use the Curve25519, Salsa20, and Poly1305 ciphers specified in [Cryptography in NaCl](https://nacl.cr.yp.to/valid.html). - -### Package Signing - -Chef Habitat packages are signed using [BLAKE2b](https://blake2.net/) checksums. BLAKE2b is a cryptographic hash function faster than MD5, SHA-1, SHA-2 and SHA3, yet provides at least as much security as the latest standard SHA-3. - -You can examine the first four lines of a `.hart` file to extract the signature from it, because it is an `xz`-compressed tarball with a metadata header. The `hab pkg header` command will do this for you. - -```bash -hab pkg header somefile.hart -``` - -outputs: - -```bash -» Reading package header for somefile.hart - -Package : somefile.hart -Format Version : HART-1 -Key Name : myorigin-19780608081445 -Hash Type : BLAKE2b -Raw Signature : a8yDoiA0Mv0CcW6xVyfkSOIZ0LW0beef4RPtvKL56MxemgG6dMVlKG1Ibplp7DUByr5az0kI5dmJKXgK6KURDzM1N2Y2MGMxYWJiMTNlYjQxMjliZTMzNGY0MWJlYTAzYmI4NDZlZzM2MDRhM2Y5M2VlMDkyNDFlYmVmZDk1Yzk= -``` - -The `.hart` file format is designed in this way to allow you to extract both the signature and the payload separately for inspection. To extract only the `xz`-compressed content, bypassing the signature, you could type this: - -```bash -tail -n +6 somefile.hart | xzcat | tar x -``` diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_design.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_design.md deleted file mode 100644 index 34e004ff08..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_design.md +++ /dev/null @@ -1,147 +0,0 @@ -+++ -title = "Supervisor Design" -aliases = ["/habitat/internals/"] -date = 2020-10-26T18:55:28-07:00 -draft = false -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Supervisor Design" - identifier = "habitat/supervisors/Supervisor Design" - parent = "habitat/supervisors" - weight = 30 -+++ - -This section will dive into the implementation details of important Chef Habitat components. These topics are for advanced users. It is not necessary to learn these concepts in order to use Chef Habitat. - -The Chef Habitat Supervisor is similar in some ways to well-known process supervisors like [systemd](https://www.freedesktop.org/wiki/Software/systemd/), [runit](http://smarden.org/runit/) or [smf](https://en.wikipedia.org/wiki/Service_Management_Facility). It accepts and passes POSIX signals to its child processes, restarts child processes if and when they fail, ensures that children processes terminate cleanly, and so on. - -Because the basic functionality of process supervision is well-known, this document does not discuss those details. Instead, this document focuses strictly on the internals of the feature that makes the Chef Habitat Supervisor special: the fact that each Supervisor is connected to others in a peer-to-peer network which we refer to as a _ring_. This allows Supervisors to share configuration data with one another and adapt to changing conditions in the ring by modifying their own configuration. - -## Important Terms - -Members -: The Butterfly keeps track of "members"; each Chef Habitat Supervisor is a single member. - -Peer -: All the members a given member is connected to are its "peers". A member is seeded with a list of "initial peers". - -Health -: The status of a given member, from the perspective of its peers. - -Rumor -: A piece of data shared with all the members of a ring; examples are election, membership, services, or configuration. - -Heat -: How many times a given rumor has been shared with a given member - -Ring -: All the members connected to one another form a Ring - -Incarnation -: A counter used to determine which message is "newer" - -## Supervisor Internals - -The Chef Habitat Supervisor is similar in some ways to well-known process supervisors like [systemd](https://www.freedesktop.org/wiki/Software/systemd/), [runit](http://smarden.org/runit/) or [smf](https://en.wikipedia.org/wiki/Service_Management_Facility). It accepts and passes POSIX signals to its child processes, restarts child processes if and when they fail, ensures that children processes terminate cleanly, and so on. - -Because the basic functionality of process supervision is well-known, this document does not discuss those details. Instead, this document focuses strictly on the internals of the feature that makes the Chef Habitat Supervisor special: the fact that each Supervisor is connected to others in a peer-to-peer network which we refer to as a _ring_. This allows Supervisors to share configuration data with one another and adapt to changing conditions in the ring by modifying their own configuration. - -## Architecture - -Supervisors are configured to form a network by using the `--peer` argument and pointing them at peers that already exist. In a real-life deployment scenario, Supervisors in a network may also have a shared encryption key, so that inter-Supervisor traffic is encrypted. (See the [security]({{< relref "keys" >}}) documentation for more details.) - -Supervisor rings can be very large, comprising thousands of supervisors. The Supervisor communication protocol is low-bandwidth and designed to not interfere with your application's actual production traffic. - -Rings are divided into _service groups_, each of which has a name. All Supervisors within a service group share the same configuration and topology. - -### Butterfly - -Chef Habitat uses a gossip protocol named "Butterfly". This protocol provides failure detection, service discovery, and leader election to the Chef Habitat Supervisor. - -Butterfly is an eventually consistent system - it says, with a very high degree of probability, that a given piece of information will be received by every member of the network. It makes no guarantees as to when that state will arrive; in practice, the answer is usually "quite quickly". - -### Transport Protocols - -Supervisors communicate with each other using UDP and TCP, both using port 9638. - -### Information Security - -Butterfly encrypts traffic on the wire using Curve25519 and a symmetric key. If a ring is configured to use transport level encryption, only members with a matching key are allowed to communicate. - -Service Configuration and Files can both be encrypted with public keys. - -### Membership and Failure Detection - -Butterfly servers keep track of what members are present in a ring, and are constantly checking each other for failure. - -#### Health States - -Ring members have one of four health states: - -Alive -: This member is responding to health checks. - -Suspect -: This member has stopped responding to our health check, and will be marked confirmed if we do not receive proof it is still alive soon. - -Confirmed -: This member has been un-responsive long enough that we can cease attempting to check its health. - -Departed -: This member has been intentionally kicked out of the ring for behavior unbecoming of a Supervisor, and is prevented from rejoining. This is accomplished with `hab` CLI commands. - -#### Failure Detection - -The essential flow for detecting a failure is: - -1. Randomize the list of all known members who are not Confirmed or Departed. -1. Every 3.1 seconds, pop a member off the list, and send it a "PING" message. -1. If we receive an "ACK" message before 1 second elapses, the member remains Alive. -1. If we do not receive an "ACK" in 1 second, choose 5 peers (the "PINGREQ targets"), and send them a "PINGREQ(member)" message for the member who failed the PING. -1. If any of our PINGREQ targets receive an ACK, they forward it to us, and the member remains Alive. -1. If we do not receive an ACK via PINGREQ with 2.1 seconds, we mark the member as Suspect, and set an expiration timer of 9.3 seconds. -1. If we do not receive an Alive status for the member within the 9.3 second suspicion expiration window, the member is marked as Confirmed. -1. Move on to the next member, until the list is exhausted; start the process again. - -When a Supervisor sends the PING, ACK and PINGREQ messages, it includes information about the 5 most recent members. This enables membership to be gossiped through the failure protocol itself. - -This process provides several nice attributes: - -- It is resilient to partial network partitions. -- Due to the expiration of suspected members, confirmation of death spreads quickly. -- The amount of network traffic generated by a given node is constant, regardless of network size. -- The protocol uses single UDP packets which fit within 512 bytes. - -### Gossip - -Butterfly uses ZeroMQ to disseminate rumors throughout the network. Its flow: - -- Randomize the list of all known members who are not Confirmed dead. -- Every second, take 5 members from the list. -- Send each member every rumor that has a Heat lower than 3; update the heat for each rumor sent. -- When the list is exhausted, start the loop again. - -Whats good about this system: - -- ZeroMQ provides a scalable PULL socket, that processes incoming messages from multiple peers as a single fair-queue. -- It has no back-chatter - messages are PUSH-ed to members, but require no receipt acknowledgement. -- Messages are sent over TCP, giving them some durability guarantees. -- In common use, the gossip protocol becomes inactive; if there are no rumors to send to a given member, nothing is sent. - -## Butterfly and SWIM - -The Butterfly protocol is a variant of [SWIM](https://prakhar.me/articles/swim) for membership and failure detection (over UDP), and a ZeroMQ based variant of [Newscast](https://www.cs.unibo.it/bison/publications/ap2pc03.pdf) for gossip. Butterfly differs from SWIM in the following ways: - -- Rather than sending messages to update member state, we send the entire member. -- We support encryption on the wire. -- Payloads are protocol buffers. -- We support "persistent" members - these are members who will continue to have the failure detection protocol run against them, even if they are confirmed dead. This enables the system to heal from long-lived total partitions. -- Members who are confirmed dead, but who later receive a membership rumor about themselves being suspected or confirmed, respond by spreading an Alive rumor with a higher incarnation. This allows members who return from a partition to re-join the ring gracefully. - -### Further Reading - -- [SWIM: Scalable Weakly-consistent Infection-style Process Group Membership -Protocol](https://www.cs.cornell.edu/projects/Quicksilver/public_pdfs/SWIM.pdf) by Abhinandan Das, Indranil Gupta, and Ashish Motivala. -- [A Robust and Scalable Peer-to-Peer Gossiping Protocol](https://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.90.8773&rep=rep1&type=pdf) by Spyros Voulgaris, Mark Jelasity, and Maarten van Steen. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_elections.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_elections.md deleted file mode 100644 index b715fc7b6d..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_elections.md +++ /dev/null @@ -1,31 +0,0 @@ -+++ -title = "Leader Elections" -date = 2020-10-26T19:05:42-07:00 -draft = false -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Leader Elections" - identifier = "habitat/supervisors/Leader Elections" - parent = "habitat/supervisors" - weight = 40 -+++ - -The Chef Habitat Supervisor performs leader election natively for service groups [topologies]({{< relref "service_group_topologies" >}}) that require one, such as _leader-follower_. - -Because Chef Habitat is an eventually-consistent distributed system, the role of the leader is different than in strongly-consistent systems. It only serves as the leader for *application level semantics*, e.g. a database write leader. The fact that a Supervisor is a leader has no bearing upon other operations in the Chef Habitat system, including rumor dissemination for configuration updates. It is _not_ akin to a [Raft](https://raft.github.io/) leader, through which writes must all be funneled. This allows for very high scalability of the Chef Habitat Supervisor ring. - -Services grouped using a leader need to have a minimum of three supervisors in order to break ties. It is also strongly recommended that you do not run the service group with an even number of members. Otherwise, in the event of a network partition with equal members on each side, both sides will elect a new leader, causing a full split-brain from which the algorithm cannot recover. Supervisors in a service group will warn you if you are using leader election and have an even number of supervisors. - -### Protocol for electing a leader - -When a service group starts in a leader topology, it will wait until there are sufficient members to form a quorum (at least three). At this point, an election cycle can happen. Each Supervisor injects an election rumor into ring, targeted at the service group, with the _exact same_ rumor, which demands an election and insists that the peer itself is the leader. This algorithm is known as [Bully](https://en.wikipedia.org/wiki/Bully_algorithm). - -Every peer that receives this rumor does a simple lexicographic comparison of its GUID with the GUID of the peer contained in that rumor. The winner is the peer whose GUID is higher. The peer then adds a vote for the GUID of the winner, and shares the rumor with others, including the total number of votes of anyone who previously voted for this winner. - -An election ends when a candidate peer X gets a rumor back from the ring saying that it (X) is the winner, with all members voting. At this point, it sends out a rumor saying it is the declared winner, and the election cycle ends. - -### Related reading - -* For more information about the Bully algorithm, see [Elections in a Distributed Computing System](http://dl.acm.org/citation.cfm?id=1309451) by Héctor García-Molina. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_launcher.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_launcher.md deleted file mode 100644 index 92cba26478..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_launcher.md +++ /dev/null @@ -1,27 +0,0 @@ -+++ -title = "Launcher" -description = "Launcher" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Launcher" - identifier = "habitat/supervisors/sup-launcher Supervisor Launcher Sidecar Process" - parent = "habitat/supervisors" - weight = 110 - -+++ - -Chef Habitat's Launcher is a sidecar process for the Supervisor which provides a mechanism for launching processes on behalf of the Supervisor. It is the entry point for running the Supervisor and is the Supervisor for the Supervisor. Whereas the Supervisor is able to automatically update itself, the Launcher is currently released a bit differently, by design; it should be rare that the Launcher ever needs to change. - -To update your Launchers, run: - -```bash -hab pkg install core/hab-launcher -``` - -Then restart the Supervisor. This will, by necessity, require a restart of supervised services, so factor that into your planning. - -The Launcher is designed to run as process 1; it is minimal by design. Its responsibilities are simply to be the parent process for the Supervisor. - -The Launcher enables the Supervisor to update itself without shutting down or re-parenting the services that the Supervisor is supervising. The Launcher is versioned separately from the Supervisor and should be updated very infrequently since an update of the Launcher could require a system restart if it is running as process 1. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_log_configuration.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_log_configuration.md deleted file mode 100644 index f3dce53fd6..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_log_configuration.md +++ /dev/null @@ -1,88 +0,0 @@ -+++ -title = "Supervisor Log Configuration" -description = "Dynamically adjust the logging configuration of a running Supervisor" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Supervisor Log Configuration" - identifier = "habitat/supervisors/sup-log-configuration" - parent = "habitat/supervisors" - weight = 90 -+++ - -With the 0.83.0 release of the Chef Habitat Supervisor, it is possible to have greater control over logging output, including the ability to dynamically adjust the logging configuration of a running Supervisor. There are two main ways of configuring logging, each of which has their own strengths and weaknesses: using environment variables, and using a configuration file. - -## Environment Variable Configuration - -It is still possible to configure logging via the `RUST_LOG` environment variable. This approach is often useful for quickly re-configuring logging (requiring a restart), or for easily configuring logging in container-based deployments. - -The configuration scheme is essentially the same as that described in the documentation of the Rust [env_logger](https://docs.rs/env_logger/0.6.1/env_logger/#enabling-logging) crate, with the exception that we do not allow additional regular expression-based filtering. The configuration values the Supervisor recognizes are described below: - -## Simple Logging Levels - -The recognized values are, in increasing verbosity (or, equivalently, in decreasing severity): `error`, `warn`, `info`, `debug`, and `trace`. - -Setting `RUST_LOG` to one of these values will cause all log messages at that verbosity and below (equivalently, that severity and above) to be printed. This includes log messages from Habitat, as well as any libraries that it uses. - -## Rust Logging Levels - -This is much finer grained than the simple logging levels above, and to fully leverage it requires some knowledge of both the internal code structure of Habitat itself, as well as of how Rust code is organized generally. Despite this, it allows you to target specific subsystems, which can be very helpful for troubleshooting. - -For example, `RUST_LOG=habitat_sup::manager=info` will cause all log messages at the `info` level or more severe (i.e., `error`, `warn`, and `info`) originating anywhere in the module hierarchy rooted at `habitat_sup::manager`. - -Note that Rust modules are identified first by the crate (or library) they come from, followed by a `::`-delimited path of module names. - -## Variations - -Multiple logging specifiers can be submitted, separated by commas. A simple logging level will act as the default, with additional module-targeted levels serving to refine the logging for the target code. If you supply multiple simple logging levels, only the last one will count. Any number of targeted logging levels are allowed, however. - -For example, `RUST_LOG=info,habitat_sup::manager=debug,tokio_reactor=error` will limit logs generally to the `info` level, while additionally allowing `debug` messages coming from the `habitat_sup::manager` module hierarchy, and restricting log messages from the `tokio_reactor` library to only `error`. - -## Dynamic, File-based Configuration - -For further control over logging output, as well as the ability to change the configuration of a running Supervisor, a configuration file is needed. This file is processed by the [log4rs](https://docs.rs/log4rs/) crate, and shares many of the same concepts as the Log4J logging system of the Java ecosystem. The `log4rs` configuration documentation can be found [here](https://docs.rs/log4rs/0.8.3/log4rs/#configuration). - -Place an appropriate YAML configuration file at `/hab/sup/default/config/log.yml` when the Supervisor starts up if you wish to take advantage of this style of configuration. Note that if such a file is present, it will take priority over any `RUST_LOG` environment variable that may also be present. - -Here is an example configuration file that mimics the default logging configuration of the Supervisor. It emits UTC timestamped message lines to standard output at the `error` level. - -```yaml -# ALWAYS keep this key in the configuration; removing it means changes -# to config won't get picked up without a restart. -# -# Uses humantime to parse the duration; see -# https://docs.rs/humantime/1.2.0/humantime/fn.parse_duration.html -refresh_rate: 5 seconds - -appenders: - stdout: - kind: console - encoder: - # See https://docs.rs/log4rs/0.8.3/log4rs/#configuration for - # formatting options - pattern: "[{d(%Y-%m-%dT%H:%M:%SZ)(utc)} {l} {module}] {message}{n}" - -root: - level: error - appenders: - - stdout -``` - -The `refresh_rate` configuration is very important. If it is present when the Supervisor starts, the file will be checked periodically for updates (according to the value of `refresh_rate`; in the above example, the file will be checked every 5 seconds). If the file changes, then the current content of the file becomes the active configuration. This allows you to, for example, increase the logging level of a running supervisor if you suspect you are running into problems. - -This dynamism also has a catch, though: you can change the refresh rate as well, and even remove it entirely. If you remove it, however, the Supervisor will stop checking for updates to the file. Any subsequent changes you might make would require a Supervisor restart to be recognized. Work is planned to make this more flexible, however. - -You can also target individual module hierarchies with this configuration scheme, just as you can with the `RUST_LOG` environment variable. For this, you will need to add a new top-level `loggers` key to the file, like so: - -```yaml -loggers: - habitat_sup::manager: - level: debug - tokio_reactor: - level: error -``` - -Here, `loggers` is a map of maps. Map keys are module paths (as described above in the `RUST_LOG` environment variable documentation), while the values are maps with additional configuration. Here, we are only setting the logging level, but more advanced configurations are possible. - -Users are encouraged to read the [log4rs configuration documentation](https://docs.rs/log4rs/0.8.3/log4rs/#configuration) for further details. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_log_keys.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_log_keys.md deleted file mode 100644 index c4751f4713..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_log_keys.md +++ /dev/null @@ -1,52 +0,0 @@ -+++ -title = "Supervisor Log Codes" -description = "Supervisor log code key reference" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Supervisor Log Codes" - identifier = "habitat/reference/sup-log-key" - parent = "habitat/reference" -+++ - -When running services with the Chef Habitat Supervisor you'll see log output similar to this: - -```output -redis.default(SR): Initializing -redis.default(SV): Starting -redis.default(O): -``` - -The letters in parentheses are called "log keys" and signify what type of log message is being shown. This can be useful for log filtering. - -They are mostly organized by the part of the Chef Habitat Supervisor code base that they are running from, so they often are of value to somebody troubleshooting problems in the Chef Habitat Supervisor source code. - -The meanings of the keys are as follows: - -| Key | Description | -|-----|-------------| -| CE | Census | -| CFG | Global configuration | -| CS | Create service: When a service is being started | -| ER | Errors | -| FW | Generic file watcher | -| HG | Messages from the HTTP gateway | -| MN | Main | -| MR | Manager | -| O | Standard output | -| PH | Package hooks | -| PK | Package | -| PT | Path | -| PW | Peer file watcher | -| SC | Service configuration | -| SH | Starting a shell with `hab sup sh` | -| SI | Unix signals | -| SOT | Structured output | -| SR | Service runtime | -| SU | Service updater | -| SV | Supervisor | -| SY | "sys" utility | -| UCW | User-config watcher | -| UR | Users utility | -| UT | Utilities | diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_networks.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_networks.md deleted file mode 100644 index 93d9637f40..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_networks.md +++ /dev/null @@ -1,107 +0,0 @@ -+++ -title = "Supervisor Networks" -description = "Robust Supervisor Networks" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Supervisor Networks" - identifier = "habitat/supervisors/sup-networks Supervisor Networks Explained" - parent = "habitat/supervisors" - weight = 60 -+++ - -Chef Habitat Supervisors communicate amongst each other using "gossip" algorithms, which underpin the membership management, leadership election, and service discovery mechanics of Chef Habitat. By simply being "peered" to a single existing Supervisor, a new Supervisor will gradually come to know about _all_ the Supervisors in a Chef Habitat network. The gossip algorithm has built-in features to counteract brief network splits, but care must be taken to set up a robust Supervisor network. - -## The Initial Peer - -While a Chef Habitat Supervisor does not need to connect with any other Supervisors in order to be useful, leveraging a network of Supervisors unlocks the full potential of Chef Habitat as a platform. In order to do this, a Supervisor must be given the address of at least one other Supervisor in this network when it starts up; this is known as the "initial peer problem". You might think of a Supervisor network as an exclusive members-only club; you must first know a member in order to become a member yourself. - -This Supervisor does _not_ know about any other Supervisors, and will (at least initially) run in complete isolation. - -```sh -hab sup run -``` - -This Supervisor, on the other hand, will start up knowing about three other Supervisors, and will quickly establish contact with each of them. Thanks to the gossip mechanism, it will also find out about every other Supervisor those initial Supervisors know about. Similarly, every other Supervisor will discover the presence of _this_ new Supervisor. - -```sh -hab sup run --peer=192.168.0.1 --peer=192.168.0.2 --peer=192.168.0.3 -``` - -It should be noted that peering is symmetric. Even though our first Supervisor above did not start out peered with any other Supervisors, it can still become part of a Supervisor network if some other Supervisor declares it to be a peer. - -## Managing Membership with SWIM - -In order for Chef Habitat's network functionality to work, the Supervisors must first know which other Supervisors they can communicate with. This is a problem of maintaining "membership lists", and is achieved using the membership protocol known as [SWIM][SWIM]. As detailed above, we must first "seed" a Supervisor's membership list with at least one "peer"; that is, another Supervisor that it can communicate with. - -Given a non-empty membership list, the Supervisor can begin probing the members of that list to see if they are still alive and running. Supervisor A sends a message to Supervisor B, effectively asking "are you still there?". If Supervisor B _is_ available, it will reply to Supervisor A, also sending contact information for up to five Supervisors that _it_ has in its membership lists (Supervisor A sends these introductions in its initial message, as well). In this way, Supervisors can both maintain and _grow_ their membership lists. In short order, Supervisor A will come to know of all the other Supervisors in the network, and they, too, will come to know of Supervisor A. - -If Supervisor A cannot establish contact with Supervisor B for some reason, it does not immediately consider it to be dead. This would be too strict, and could lead to unnecessary service "flapping". Instead, Supervisor A will consider Supervisor B "suspect". In this case, it will ask Supervisor C (another Supervisor in its membership list) if _it_ can contact Supervisor B. If Supervisor C can make contact, it relays that information back to Supervisor A, which will then consider Supervisor B to be alive again, and _not_ suspect. This scenario can arise, for example, if there is a network split between Supervisors A and B, but not between A and C, or B and C. Similarly, network congestion could delay messages such that Supervisor A's request times out before Supervisor B's reply can make it back. - -If no Supervisor can make contact with Supervisor B, either directly or indirectly, the network comes to view Supervisor B as "confirmed" dead. In this case, Supervisor B is effectively removed from all membership lists across the network. As a result, no Supervisors try to contact it again. This is ultimately what happens when you shut down a Supervisor; the rest of the network realizes that it is gone and can reconfigure any services to no longer communicate with any services that were running on it. - -If, on the other hand, Supervisor B is started back up again, it can rejoin the network. All the other Supervisors will (through the same SWIM mechanism described) recognize that it is back, and will mark it as alive once again. Services will be reconfigured to communicate with Supervisor B's services as appropriate. - -This mechanism forms the foundation of the Chef Habitat network, but cannot by itself provide a completely robust network. For that, we need something additional. - -## Permanent Peers - -An important thing to keep in mind about the basic SWIM mechanism is that if two Supervisors are separated from each other for a long enough amount of time, they will each come to view the other as being dead, and will not try to reestablish contact. While this is the behavior you want when you legitimately shut a Supervisor down, it is definitely _not_ the behavior you want if your Chef Habitat network experiences an extended network incident. In such a case, you could end up with two (or more!) smaller Supervisor networks that are all still _internally_ connected, but completely disconnected _from each other_. Supervisors in "Network A" would view those in "Network B" as dead, and vice versa. Once network connectivity had been restored, you would continue to have a fractured network, because each network would collectively consider the other to still be dead. - -By starting a few Supervisors in the network using the `--permanent-peer` option, an additional bit of information is gossipped about these Supervisors. In effect, it tells all other Supervisors it communicates with to _always_ try to reestablish contact with it, even if that Supervisor considers the "permanent" Supervisor to be dead. This provides a mechanism by which split networks can stitch themselves together again after the split has been resolved. - -## The "Bastion Ring" - -Defining a few Supervisors to be "permanent peers" _will_ provide a robust network, but unless done with care, it can be less than ideal. We recommend running a small number of Supervisors as permanent peers, but _to run no services on those Supervisors_. In modern dynamic architectures, it's common for nodes to come and go; VMs may get shut down, containers can be rescheduled, and so on. If you were to go to the extreme and have _all_ your Supervisors be permanent peers, you would end up with unnecessary network traffic as the Supervisors come and go as the infrastructure evolves across time. Each Supervisor would try to maintain contact with every Supervisor that had ever been a member of the network! - -If your permanent peer Supervisors are not running any services, they will be less subject to the pressures that would cause service-running Supervisors to come and go. They can exist solely to anchor the entire Supervisor network. - -## Pulling It All Together: A Robust Supervisor Network - -With all this, we can come up with a robust Chef Habitat network architecture. In fact, this is the same architecture the Chef Habitat team uses to run the public [Builder service](https://bldr.habitat.sh). - -### Create the Bastion Ring - -First, set up three Supervisors as permanent peers, all mutually peered to each other (The labels "A", "B", and "C" are stand-ins for the IP addresses at which these Supervisors are reachable): - -``` sh -# Supervisor "A" -hab sup run --permanent-peer --peer=B --peer=C - -# Supervisor "B" -hab sup run --permanent-peer --peer=A --peer=C - -# Supervisor "C" -hab sup run --permanent-peer --peer=A --peer=B -``` - -These Supervisors should never be used to run services. They _can_ however, serve as convenient, well-known, and stable entry points to the network for doing things like injecting configurations using `hab config apply`, adding files using `hab file upload`, or departing Supervisors using `hab sup depart`. - -### Peer Additional Supervisors to the Bastion Supervisors - -Each additional Supervisor you add to the network should be peered to _at least one_ of the bastion ring Supervisors. Technically speaking, only one peer is necessary, as that provides access to the rest of the network. However, it could be possible to not fully connect to all of them if, say, the Supervisor joined _during_ a network split event. Out of convention and redundancy, we peer to _all_ the bastion ring Supervisors, like so: - -``` sh -# Supervisor "D" (a "normal" Supervisor) -hab sup run --peer=A --peer=B --peer=C -``` - -This Supervisor _should_ be used to run services, but _should not_ be started as a permanent peer. - -## Conclusion - -Hopefully, the above discussion has given you a better idea of how Chef Habitat's networking works, and how you can best take advantage of it to provide a robust network foundation for the services you run. - -For those that like to keep things succinct, the above advice can be summed up thusly: - -1. Run three mutually-peered, permanent Supervisors -2. Never run services on those Supervisors -3. Peer all other Supervisors to those first three - -## Related Reading - -If you would like additional details, the following technical journal articles describe the algorithms that form the basis of Chef Habitat's gossip system: - -* [SWIM: Scalable Weakly-consistent Infection-style Process Group Membership Protocol](https://www.cs.cornell.edu/projects/Quicksilver/public_pdfs/SWIM.pdf) by Abhinandan Das, Indranil Gupta, Ashish Motivala. -* [A Robust and Scalable Peer-to-Peer Gossiping Protocol](https://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.90.8773&rep=rep1&type=pdf) by Spyros Voulgaris, Mark Jelasity, and Maarten van Steen. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_pkg_config.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_pkg_config.md deleted file mode 100644 index 35b360514c..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_pkg_config.md +++ /dev/null @@ -1,22 +0,0 @@ -+++ -title = "Supervisor Configuration" -description = "Configure the Supervisor for faster package development" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Supervisor Package Configuration" - identifier = "habitat/supervisors/sup-pkg-config" - parent = "habitat/supervisors" - weight = 100 -+++ - -To assist in creating new packages, or modifying existing ones, the Supervisor has an option to allow you to use the configuration directly from a specific directory, rather than the one it includes in the compiled artifact. This can significantly shorten the cycle time when working on configuration and application lifecycle hooks. - -Build the plan as you normally would. When you start the Supervisor, pass the name of the directory with your plan inside it: - -```bash -$ hab sup run core/redis --config-from /src -``` - -The Supervisor will now take its configuration and hooks from /src, rather than from the package you previously built. When the configuration is as you want it, do a final rebuild of the package. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_remote_control.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_remote_control.md deleted file mode 100644 index 88ab70a4dc..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_remote_control.md +++ /dev/null @@ -1,108 +0,0 @@ -+++ -title = "Control Supervisors Remotely" -description = "Controlling Supervisors Remotely" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Remote Control" - identifier = "habitat/supervisors/sup-remote-control" - parent = "habitat/supervisors" - weight = 120 -+++ - -Since the 0.56.0 Supervisor release, it is possible to command and control one or more Supervisors from a remote location. Before this, the only way to interact with a Supervisor was by taking action directly on machine on which the Supervisor was running. While that is still an option (and is indeed the default behavior), remote command and control opens up more possibilities for using and managing Chef Habitat. - -Here, we'll discuss how this is implemented, how it can be enabled in your Chef Habitat deployments, and how it can be used. - -## Remote Command and Control Overview - -The Chef Habitat Supervisor uses a defined TCP protocol for all interactions; the `hab` CLI tool is the client for this protocol, and the Supervisor is the server. Interactions are authenticated using a shared secret. - -Previously, in order to run `core/redis` on a Supervisor running on (say), `hab1.mycompany.com`, you would have to have direct access to the machine (as well as root privileges) in order to load the service, which might look like this: - -``` -ssh hab1.mycompany.com -sudo hab svc load core/redis -``` - -Now, using the remote control capabilities of the Supervisor, this could be accomplished from a workstation or bastion host with an invocation that could be as simple as this: - -``` -hab svc load core/redis --remote-sup=hab1.mycompany.com:9632 -``` - -No direct host access is necessary, and multiple Supervisors can be controlled from one central location. - -### Remote Control is Optional - -Operating Chef Habitat Supervisors remotely is purely optional; you must take positive action to enable this behavior. If you prefer, you can continue to manage Supervisors through on-the-box direct action, as before, and likely without any changes to your current procedures. Read on for further details about how to enable this ability, and how local interaction continues to operate through a new implementation. - -## Managing Shared Supervisor Secrets - -Authentication between client (`hab` CLI) and server (Supervisor) is achieved using a shared secret. The `hab` CLI receives its secret from a configuration file (`~/.hab/config/cli.toml`) or from an environment variable (`HAB_CTL_SECRET`). The Supervisor reads its secret from its `CTL_SECRET` file, located at `/hab/sup/default/CTL_SECRET`. When the value used by `hab` matches the one used by the Supervisor, the requested command is carried out. - -### Create a Secret - -Shared secrets are created in one of two ways. - -First, when a Supervisor starts up, will create a new secret in `/hab/sup/default/CTL_SECRET` automatically if one does not already exist. This is helpful for transparently upgrading older Supervisors and continuing to allow local interactions. - -Second, and most recommended, users can generate a new secret using `hab sup secret generate`: - -``` -hab sup secret generate -VKca6ezRD0lfuwvhgeQLPSD0RMwE/ZYX5nYfGi2x0R1mXNh4QZSpa50H2deB85HoV/Ik48orF4p0/7MuVNPwNA== -``` - -This generates a new secret, printing it to standard output. Using the provisioner or configuration management tool of your choice, you can then use this value to create your own `/hab/sup/default/CTL_SECRET` file, ensuring that your Supervisor(s) are using a pre-determined key, instead of each making their own. - -If you have a pre-existing fleet of Supervisors which have already been started up with their own individually-generated secrets, you will likely want to overwrite their existing `CTL_SECRET` files with one that has a key of your own creation. - -If you are using a raw container-based deployment (i.e., not a managed platform like Kubernetes), you will want to mount an appropriate `CTL_SECRET` file into the container. - -### Configure the Hab Cli with Your Secret - -Once you have a secret, you can add it to your local `hab` configuration file, preferably by running `hab cli setup` and following the interactive prompts. Alternatively, you can export it into your environment: - -``` -export HAB_CTL_SECRET="VKca6ezRD0lfuwvhgeQLPSD0RMwE/ZYX5nYfGi2x0R1mXNh4QZSpa50H2deB85HoV/Ik48orF4p0/7MuVNPwNA==" -``` - -Note that your `hab` configuration file only keeps a single "secret" entry, and exporting a single secret into your environment does effectively the same thing. An assumption of this arrangement is that all Supervisors you wish to interact with have the same shared secret; if you wish to control a set of Supervisors that do not all use the same shared secret, you will need to manage the mapping of secret-to-supervisor yourself, which might look something like this: - -``` -HAB_CTL_SECRET=${secret_for_supervisor_1} hab svc load ... --remote-sup=${address_of_supervisor_1} -HAB_CTL_SECRET=${secret_for_supervisor_2} hab svc load ... --remote-sup=${address_of_supervisor_2} -# etc. -``` - -## Configuring Supervisors for Remote Command and Control - -As stated earlier, the Supervisor reads its secret from its `/hab/sup/default/CTL_SECRET` file, the contents of which you can control using `hab sup secret generate` and your chosen provisioner / deployment tooling. This ensures that the shared secret is in place, but one more step must be taken to fully enable the feature. - -By default, the Supervisor's "control gateway" listens on the `127.0.0.1` interface for incoming commands. This means that it can only receive commands from the same machine, and not from remote clients. If you wish to control a Supervisor remotely, you'll have to start the Supervisor setting its `--listen-ctl` option to an appropriate interface and port (9632 is the default control gateway port): - -``` -hab sup run --listen-ctl=0.0.0.0:9632 -``` - -This Supervisor would now be able to be controlled via any network interface (provided the request used the appropriate shared secret, of course). As always, be sure to use the appropriate interface values for your specific situation (e.g., pass an internal network-facing interface rather than a publicly-exposed interface). - -## Targeting a Remote Supervisor - -Throughout this documentation are numerous examples of interacting with a Supervisor; commands like `hab svc load`, `hab svc start`, `hab svc stop`, etc. all generate requests using the Supervisor's defined interaction protocol. They all operate over TCP, even in the default case of interacting with a Supervisor on the same host. - -In order to target a remote Supervisor, you must have the appropriate shared secret available, as described above (either in the environment or in the `hab` CLI configuration file), and you must also specify the specific Supervisor using the `--remote-sup` option. The value for this option should correspond to the value of `--listen-ctl` the Supervisor was started with; it is the address and port at which the Supervisor's control gateway may be reached. All Supervisor interaction commands accept a `--remote-sup` option for such targeting. - -## Local Supervisor Interactions - -Without specifying `--remote-sup`, the `hab` CLI will always try to connect to a Supervisor running on the current host. It must still use the correct shared secret, however. As a last resort, if no secret is found in either a configuration file or an environment variable, the `hab` CLI will attempt to read one from `/hab/sup/default/CTL_SECRET`. In this way, it will use the same secret that the local Supervisor is using, enabling the request to proceed. - -## Protocol Versioning and `hab` Versions - -Before the 0.56.0 release of Chef Habitat, the interaction between `hab` and the Supervisor was not formally defined, and relied on making changes to files on disk. As a result, it was often possible to continue interacting with a newer Supervisor using an older version of the `hab` CLI. This was particularly noticeable when the Supervisor was configured to automatically update itself; the Supervisor would continue upgrading over time, while the `hab` CLI binary remained at whatever version it was when it was originally installed, because each of the two executable were distributed in separate packages. - -For the near term, `hab` and the Supervisor are still distributed separately, as `core/hab` and `core/hab-sup`, respectively. To interact with 0.56.0 or later Supervisors, users will need to use an 0.56.0 or later `hab` binary, even if they wish to continue interacting with their Supervisors only locally. This may require a manual upgrade for the `hab` binary, which can be done by running `hab pkg install core/hab -b -f`. In the near future, we hope to consolidate all of Chef Habitat's functionality into a single package (if not a single binary), which will make it easier to manage going forward. - -The interaction protocol is defined using Google's [Protocol Buffers](https://developers.google.com/protocol-buffers/); it is our explicit goal that all future changes to the protocol will happen in a backward-compatible way. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_rings.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_rings.md deleted file mode 100644 index 5ba5afec1c..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_rings.md +++ /dev/null @@ -1,32 +0,0 @@ -+++ -title = "Setting Up a Ring" -description = "Setting Up a Ring" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Setting Up a Ring" - identifier = "habitat/supervisors/sup-rings" - parent = "habitat/supervisors" - weight = 50 -+++ - -## Bastion Ring / Permanent Peers - -A "Bastion Ring" is a pattern for preventing rumor loss and a split brain in a network of Chef Habitat Supervisors - it is highly recommended for any real environment use case. Create a minimum of 3 Supervisors and join them together. They should not run any services and they should be marked as permanent peers - their only job is to spread rumors to each other. Then, when you provision additional Supervisors pass the network address of each Supervisor running in the Bastion Ring to the `--peer` argument of `hab sup run`. It's recommended to create a Bastion Ring in any network zones which may become partitioned due to a hardware failure. For example, if you have a Chef Habitat ring spanning multiple data centers and clouds, each should have a bastion ring of a minimum of 3 Supervisors in addition to the Supervisors running your services. - -## Using a Scheduler - -**Note:** If you are using a container scheduler such as the Kubernetes `kube-scheduler`, Docker Swarm mode, Mesos DC/OS's Marathon or Chronos, or a PaaS such as Cloud Foundry, you should not follow the bastion ring pattern, because the scheduler handles persistence and orchestration on your behalf. - -More resources on schedulers: - -- [Chef Habitat Container Orchestration]({{< relref "container_orchestration" >}}) -- Kubernetes `kube-scheduler`: https://kubernetes.io/docs/concepts/scheduling-eviction/kube-scheduler -- Docker Swarm mode: https://docs.docker.com/engine/swarm -- Mesos DC/OS Marathon or Chronos: https://mesosphere.github.io/marathon/ -- Cloud Foundry: https://www.habitat.sh/get-started/cloudfoundry - -## Initial Peer(s) - -The initial peer(s) is a requirement of any distributed system. In Chef Habitat, a new Supervisor that is starting up looks for an initial peer(s) to join to begin sharing information about the health and status of peers and other services, to increase the health of the overall Ring. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_run.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_run.md deleted file mode 100644 index aa28319a88..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_run.md +++ /dev/null @@ -1,140 +0,0 @@ -+++ -title = "Running Chef Habitat Supervisors" -description = "Running Chef Habitat Packages" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Running Supervisors" - identifier = "habitat/supervisors/sup-run Run Packages on the Supervisor" - parent = "habitat/supervisors" - weight = 20 - -+++ - -Use Chef Habitat packages to start services under the Chef Habitat Supervisor. At runtime, you can join services together in a service group running the same topology, send configuration updates to that group, and more. You can also export the Supervisor together with the package to an external immutable format, such as a Docker container or a virtual machine. - -> Note Linux-based packages can run on Linux distributions running kernel 2.6.32 or later. Windows-based packages can run on Windows Server 2012 or later and Windows 8 64-bit or later. - -Information about [installing Chef Habitat]({{< relref "install_habitat" >}}) and configuring your workstation can be found in the previous section. - -## Starting the Supervisor - -In order to run a Chef Habitat-packaged service, you must first run a Chef Habitat Supervisor. There are two ways to start up a Supervisor, and it is important to know the implications of each, and which method is appropriate for your circumstances. These instructions describe the behavior of the 0.56.0 Supervisor and later, which dramatically simplified how Supervisors start up. These instructions also deal with the Supervisor "by itself"; later on, we'll see how to integrate it into different operational scenarios (e.g., systemd, Windows Services, etc.). It is useful to understand the underlying concepts first. - -For further details about these commands, including all the arguments and options they take, please consult [the hab documentation]({{< relref "habitat_cli" >}}). - -hab sup run -: Executing `hab sup run` will start a Supervisor process in the foreground. If this is the first time a Supervisor has been run on the system, nothing else will happen; the process will be waiting for the user to "load" services into it. However, if this is _not_ the first time the Supervisor has been run, any previously loaded services that were not "stopped" (i.e., told not to run) will be started up as well. - -When executing `hab sup run`, additional options can be passed that allow the Supervisor to communicate with other Supervisors (such as `--peer`, `--permanent-peer`, etc.), forming a connected network of Supervisors; this is the communication backbone that any services running on the Supervisors use to communicate with each other. - -hab sup run \ -: When you pass a package identifier (e.g., `core/redis`) as an argument to `hab sup run`, it will start up a Supervisor process, and then load and start the given package in what is effectively a single operation. This is a convenience that is intended primarily for container entry-point workflows, where a single defined service is the only thing ever intended to run on the Supervisor, but it can also be used for local testing or experimentation. - -This version of `hab sup run` can also accept options that affect how the _package_ should run, such as `--strategy` and `--topology`, in addition to the aforementioned Supervisor-specific options. It can be thought of as running the identifier-less `hab sup run`, along with a `hab sup load`, all as a single command. - -### Selecting a startup method - -In most cases, you should always start up a Supervisor explicitly, using `hab sup run` _without_ a package identifier argument, _especially_ in production environments. - -The `` invocation mixes Supervisor-specific and service-specific options, it can sometimes be difficult to reason about, depending on how complex your usecase is. As a result, that form should be limited to constrained container-based usecases, and perhaps local simple testing or evaluation scenarios. Additionally, since a Supervisor has state -- the services it is manages -- you may end up starting additional services, depending on what you've done in the past on the same machine. That is, `hab sup run ` is not, in general, synonymous with "only run this single service". - -For all other uses, it is far preferable to start a Supervisor using the identifier-less `hab sup run` invocation, and manage the population of services it runs using `hab svc load` and other commands. - -Throughout this documentation, unless otherwise explicitly stated, assume that a Supervisor has been started with `hab sup run`, and that any services were loaded using a separate `hab svc load` invocation. - -## Testing a package locally - -Packages can be tested in the interactive studio environment or natively on a workstation running Linux or Windows. - -When entering an interactive studio, a Supervisor is started for you in the background by default. To run packages inside of this Supervisor: - -1. [Build a package]({{< relref "pkg_build" >}}) inside an interactive studio. Do not exit the studio after it is built. -2. To start your service in the running Supervisor, type `hab svc load yourorigin/yourname`, substituting the name and origin of the package you built in Step 1. Your service should now be running. - -Because the Supervisor is running in the background, you will not see the Supervisor output as you start your service. However you can use the `sup-log` (or `Get-SupervisorLog` on Windows) command that will stream the tail of the Supervisor output (you can also look at the contents of `/hab/sup/default/sup.log`, which is where the Studio directs its Supervisor output). - -If your host machine is running Linux, do the following to run your packages for one-off evaluations (not production uses!): - -* Add the `hab` user and group. - - ```bash - $ sudo adduser --group hab - $ sudo useradd -g hab hab - ``` - -* Run the `hab` Supervisor as root. - - ```bash - $ sudo hab sup run yourorigin/yourname - ``` - -You may use the same `hab run` command on Windows but omit the `sudo` command. However, you should be inside of an elevated shell. Also, note that the `hab` user is not necessary on Windows. If it is absent, services will run under the identity of the current user. If a `hab` user is present, you will need to provide its password via the`--password` argument: - -```bash -PS C:\> $cred = Get-Credential hab -PS C:\> hab sup run yourorigin/yourname --password $cred.GetNetworkCredential().Password -``` - -In all cases, you may wish to run `hab svc unload /` when you are done working with your package, to remove it from the Supervisor. Otherwise, your Supervisor will try to start your service each time it start up. - -For more structured ways of running the Chef Habitat Supervisor on servers, please see [Running Chef Habitat on Servers]({{< relref "running_habitat_servers" >}}). - -## Loading a Service - -To load a service into a Supervisor, you use the `hab svc load` subcommand. As an example, to load `yourorigin/yourname` in a Leader topology, with a Rolling update strategy, and a Group of "acme", run the following: - -```bash -$ hab svc load yourorigin/yourname --topology leader --strategy rolling --group acme -``` - -Running the `hab svc load` subcommand multiple times with different package identifiers will result in multiple services running on the same Supervisor. Let's add `core/redis` to the Supervisor for some fun: - -```bash -$ hab svc load core/redis -``` - -## Unloading a Service - -To remove a service from a Supervisor, you use the `hab svc unload` subcommand. If the service is was running, then it will be stopped first, then removed. This means that the next time the Supervisor is started (or restarted), it will not run this unloaded service. For example, to remove the `yourorigin/yourname` service: - -```bash -$ hab svc unload yourorigin/yourname -``` - -## Stopping a Running Service - -Sometimes you need to stop a running service for a period of time, for example during a maintenance outage. Rather than completely removing a service from supervision, you can use the `hab svc stop` subcommand which will shut down the running service and leave it in this state until you start it again with the `hab svc start` subcommand, explained next. This means that all service-related options such as service topology, update strategy, etc. are preserved until the service is started again. For example, to stop the running `core/redis` service: - -```bash -$ hab svc stop core/redis -``` - -## Restarting a Stopped Service - -To resume running a service which has been loaded but stopped (via the `hab svc stop` subcommand explained above), you use the `hab svc start` subcommand. Let's resume our `core/redis` service with: - -```bash -$ hab svc start core/redis -``` - -> Note: in Chef Habitat versions prior to 0.56.0, `hab svc start` could also be used to load up a service if it wasn't already loaded. In 0.56.0 and later, however, this has changed; `hab svc start` can only operate on services that have previously been loaded. - -## Querying the Supervisor for Service Status - -You can query all services currently loaded or running under the local Supervisor using the `hab svc status` command. This command will list all services loaded by the Supervisor along with their current state. The `status` command includes the version and release of the service and for services that are running, it will include the `PID` of the running service. - -To retrieve status for an individual service, you can pass the service identifier: - -```bash -$ hab svc status core/mysql -``` - -The following exit codes are emitted by the `status` command: - -* `0` - The status command successfully reports status on loaded services -* `1` - A generic error has occurred calling the `hab` cli -* `2` - A service identifier was passed to `hab svc status` and that service is not loaded by the Supervisor -* `3` - There is no local running Supervisor - diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_secure.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_secure.md deleted file mode 100644 index a41d5ecc03..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_secure.md +++ /dev/null @@ -1,103 +0,0 @@ -+++ -title = "Securing Supervisor Networks" -description = "Securing Supervisor Networks" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Securing Networks" - identifier = "habitat/supervisors/using-encryption" - parent = "habitat/supervisors" - weight = 80 - -+++ - -By default, a Supervisor runs unsecured. It communicates with other Supervisors in cleartext, and it allows any user to apply new configuration without authentication. While this is beneficial for demonstrating the concepts of Chef Habitat, users will want to provide external security on production deployments of Chef Habitat Supervisor networks. - -There are several types of security measures: - -* Wire encryption of inter-Supervisor traffic -* Trust relationships between supervisors and users - -## Wire Encryption - -Supervisors running in a ring can be configured to encrypt all traffic between them. This is accomplished by generating a _ring key_, which is a symmetric shared secret placed into the Supervisor environment prior to starting it. - -### Generating a Ring Key - -1. Generate a ring key using the `hab` command-line tool. This can be done on your workstation. The generated key has the `.sym.key` extension, indicating that it is a symmetric pre-shared key, and is stored in the `$HOME/.hab/cache/keys` directory. - - ```bash - $ hab ring key generate - ``` - -2. Copy the key file to the environment where the Supervisor will run, into the `/hab/cache/keys` directory. Ensure that it has the appropriate permissions so only the Supervisor can read it. -3. Start the Supervisor with the `-r` or `--ring` parameter, specifying the name of the ring key to use. - - ```bash - $ hab sup run --ring - $ hab svc load / - ``` - -4. The Supervisor becomes part of the named ring `` and uses the key for network encryption. Other supervisors that now attempt to connect to it without presenting the correct ring key will be rejected. -5. It is also possible to set the environment variable `HAB_RING_KEY` to the contents of the ring key; for example: - - ```bash - $ env HAB_RING_KEY=$(cat /hab/cache/keys/ring-key-file) hab sup run - $ hab svc load / - ``` - -## Service Group Encryption - -Supervisors in a service group can be configured to require key-based authorization prior to allowing configuration changes. In this scenario, the Supervisor in a named service group starts up with a key for that group bound to an _organization_. This allows for multiple service groups with the same name in different organizations. - -As explained in the [security overview]({{< relref "sup_crypto" >}}), this process also requires the generation of a user key for every user making configuration updates to the Supervisor network. - -### Generating Service Group Keys - -1. Generate a service group key using the `hab` command-line tool. This can be done on your workstation. Because asymmetric encryption is being used, two files will be generated: a file with a `.box.key` extension, which is the service group's private key, and a file with a `.pub` extension, which is the service group's public key. - - ```bash - $ hab svc key generate service-group-name.example - ``` - -2. This generated a service group key for the service group `service-group-name.example` in the organization ``. Copy the `.box.key` private key to the environment where the Supervisor will run into the `/hab/cache/keys` directory. Ensure that it has the appropriate permissions so that only the Supervisor can read it. -3. Start the Supervisor, specifying both the service group and organization that it belongs to: - - ```bash - $ hab sup run --org --group service-group-name.example - $ hab svc load / - ``` - -4. Only users whose public keys that the Supervisor already has in its cache will be allowed to reconfigure this service group. If you need to generate a user key pair, see the next section. - -### Generating User Keys - -The user key is used to encrypt configuration data targeted for a particular service group. - -1. Generate a user key using the `hab` command-line tool. This can be done on your workstation. Because asymmetric encryption is being used, two files will be generated: a file with a `.box.key` extension, which is the user's private key, and a file with a `.pub` extension, which is the user's public key. -2. Distribute the user's public key to any Supervisor that needs it, into the `/hab/cache/keys` directory. The user will be able to reconfigure that Supervisor, provided they encrypted the configuration update using the service group's public key. - -## Apply Configuration Changes - -The `hab config apply` and `hab file upload` commands will work as usual when user/service group trust relationships are set up in this way. - -If a running Supervisor cannot decrypt a secret due to a missing key, it will retry with exponential backoff starting with a one-second interval. This allows an administrator to provide the Supervisor with the key to resume normal operations, without taking down the Supervisor. - -## Identifying Key Types - -To aid the user in the visual identification of the many varieties of keys in use by Chef Habitat, a key itself is in cleartext and contains a header on the first line indicating what kind of key it is. The file extension and, in some situations, the format of the file name, provide additional guidance to the user in identifying the type of key. - -`YYYYMMDDRRRRRR` denotes the creation time and release identifier of that key. - -| Key Type | Header | Filename Format | -|----------|--------|-----------------| -| Private origin signing key | SIG-SEC-1 | originname-YYYYMMDDRRRRRR.sig.key | -| Public origin signing key | SIG-PUB-1 | originname-YYYYMMDDRRRRRR.pub.key | -| Ring wire encryption key | SYM-SEC-1 | ringname-YYYYMMDDRRRRRR.sym.key | -| Private service group key | BOX-SEC-1 | service-group.env@org-YYYYMMDDRRRRRR.box.key | -| Public service group key | BOX-PUB-1 | service-group.env@org-YYYYMMDDRRRRRR.pub | -| Private user key | BOX-SEC-1 | username-YYYYMMDDRRRRRR.box.key | -| Public user key | BOX-PUB-1 | username-YYYYMMDDRRRRRR.pub | - -Keys that contain `SEC` in their header should be guarded carefully. Keys that contain `PUB` in their header can be distributed freely with no risk of information compromise. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_update.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_update.md deleted file mode 100644 index 60c66e9330..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/sup_update.md +++ /dev/null @@ -1,37 +0,0 @@ -+++ -title = "Updating the Supervisor" -description = "Updating the Supervisor" -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Updating Supervisors" - identifier = "habitat/supervisors/updating" - parent = "habitat/supervisors" - weight = 130 - -+++ - -Each new Chef Habitat release brings a new Supervisor that includes all bug fixes and enhancements since the last release. It's a good idea to stay relatively up to date with your running Supervisors. When updating Supervisors in production, you usually will not want to shut down all of your running services while you perform the update. That could incur an outage or require a maintenance window. Chef Habitat provides a couple of ways for you to update a Supervisor without stopping your running services. - -## Manual Update - -While an older version of the Supervisor is running, install the newer Supervisor into your local Chef Habitat package repository: - -```bash -hab pkg install core/hab-sup -``` - -This will not update the running Supervisor. It simply downloads the new Supervisor and stores it in your `/hab/pkgs` store. To update the running Supervisor, restart it with: - -```bash -hab sup restart -``` - -This will not restart the running services; it will only restart the supervisor service. - -## Automatic Update - -You can configure the Supervisor to automatically update itself when new Supervisor releases become available. This is done by adding the `--auto-update` flag to `hab sup run` or by setting `auto_update` to `true` in `/hab/sup/default/config/sup.toml`. By default, the Supervisor will check for updates every 60 seconds. This can be adjusted by changing the `--auto-update-period` to a different number of seconds. - -If you want the Supervisor to look for updated Supervisor releases in a on-prem depot or in a channel other than `stable`, then use the `--url` and `--channel` arguments of `hab sup run` to point to the desired Builder URL and release channel. diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/supervisor_api.md b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/supervisor_api.md deleted file mode 100644 index 0fdd7985b0..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/supervisor_api.md +++ /dev/null @@ -1,18 +0,0 @@ -+++ -title = "Chef Habitat Supervisor API" -aliases = ["/habitat/api/supervisor/"] -date = 2019-03-06T17:25:30-07:00 -draft = false -layout = "data-api" -style_sheet = "/habitat-api-styles.css" -api_file_path = "/habitat-api-docs/sup-api.json" -return_page = "/habitat/" -description = "Chef Habitat Supervisor API documentation." - -[menu] - [menu.habitat] - title = "Supervisor API" - parent = "habitat/reference/api" - identifier = "habitat/reference/api Supervisor API" -+++ - diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/habitat-api-docs/sup-api.json b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/habitat-api-docs/sup-api.json deleted file mode 100644 index d23653bee3..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/habitat-api-docs/sup-api.json +++ /dev/null @@ -1,796 +0,0 @@ -{ - "openapi": "3.0.0", - "info": { - "title": "Habitat Supervisor", - "version": "1.0" - }, - "servers": [ - { - "url": "http://{rootUri}", - "variables": { - "rootUri": { - "description": "The root URI for the Habitat Supervisor", - "default": "" - } - }, - "x-amf-parameters": { - "rootUri": { - "description": "The root URI for the Habitat Supervisor", - "example": "localhost:9631" - } - } - } - ], - "consumes": [ - "application/json" - ], - "produces": [ - "application/json" - ], - "paths": { - "/butterfly": { - "get": { - "description": "Butterfly debug output", - "responses": { - "200": { - "description": "", - "content": { - "application/json": {} - } - } - } - } - }, - "/census": { - "get": { - "description": "Census debug output", - "responses": { - "200": { - "description": "", - "content": { - "application/json": {} - } - } - } - } - }, - "/services": { - "get": { - "description": "List information of all loaded services", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "array", - "x-amf-merge": [ - { - "type": "array", - "items": { - "$ref": "#/components/schemas/service" - } - } - ] - } - } - } - }, - "503": { - "description": "Supervisor hasn't fully started. Try again later." - } - } - } - }, - "/services/{name}/{group}": { - "parameters": [ - { - "name": "name", - "required": true, - "in": "path", - "schema": { - "type": "string" - } - }, - { - "name": "group", - "required": true, - "in": "path", - "schema": { - "type": "string" - } - } - ], - "get": { - "description": "Show information of a single loaded service", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "x-amf-merge": [ - { - "$ref": "#/components/schemas/service" - } - ] - } - } - } - }, - "404": { - "description": "Service not loaded" - }, - "503": { - "description": "Supervisor hasn't fully started. Try again later." - } - } - } - }, - "/services/{name}/{group}/config": { - "parameters": [ - { - "name": "name", - "required": true, - "in": "path", - "schema": { - "type": "string" - } - }, - { - "name": "group", - "required": true, - "in": "path", - "schema": { - "type": "string" - } - } - ], - "get": { - "description": "Get last configuration for the given service group", - "responses": { - "200": { - "description": "", - "content": { - "application/toml": { - "schema": { - "type": "object" - } - } - } - }, - "404": { - "description": "Service not loaded" - }, - "503": { - "description": "Supervisor hasn't fully started. Try again later." - } - } - } - }, - "/services/{name}/{group}/health": { - "parameters": [ - { - "name": "name", - "required": true, - "in": "path", - "schema": { - "type": "string" - } - }, - { - "name": "group", - "required": true, - "in": "path", - "schema": { - "type": "string" - } - } - ], - "get": { - "description": "Health check status and output for the given service group", - "responses": { - "200": { - "description": "Health Check - Ok / Warning", - "content": { - "application/json": { - "schema": { - "type": "object", - "x-amf-merge": [ - { - "$ref": "#/components/schemas/healthCheckOutput" - } - ] - } - } - } - }, - "404": { - "description": "Service not loaded" - }, - "500": { - "description": "Health Check - Unknown" - }, - "503": { - "description": "Health Check - Critical" - } - } - } - }, - "/services/{name}/{group}/{organization}": { - "parameters": [ - { - "name": "name", - "required": true, - "in": "path", - "schema": { - "type": "string" - } - }, - { - "name": "group", - "required": true, - "in": "path", - "schema": { - "type": "string" - } - }, - { - "name": "organization", - "required": true, - "in": "path", - "schema": { - "type": "string" - } - } - ], - "get": { - "description": "Show information of a single loaded service scoped to an organization", - "responses": { - "200": { - "description": "", - "content": { - "application/json": { - "schema": { - "type": "object", - "x-amf-merge": [ - { - "$ref": "#/components/schemas/service" - } - ] - } - } - } - }, - "404": { - "description": "Service not loaded" - }, - "503": { - "description": "Supervisor hasn't fully started. Try again later." - } - } - } - }, - "/services/{name}/{group}/{organization}/config": { - "parameters": [ - { - "name": "name", - "required": true, - "in": "path", - "schema": { - "type": "string" - } - }, - { - "name": "group", - "required": true, - "in": "path", - "schema": { - "type": "string" - } - }, - { - "name": "organization", - "required": true, - "in": "path", - "schema": { - "type": "string" - } - } - ], - "get": { - "description": "Get last configuration for the given service group", - "responses": { - "200": { - "description": "", - "content": { - "application/toml": { - "schema": { - "type": "object" - } - } - } - }, - "404": { - "description": "Service not loaded" - }, - "503": { - "description": "Temporarily couldn't load configuration" - } - } - } - }, - "/services/{name}/{group}/{organization}/health": { - "parameters": [ - { - "name": "name", - "required": true, - "in": "path", - "schema": { - "type": "string" - } - }, - { - "name": "group", - "required": true, - "in": "path", - "schema": { - "type": "string" - } - }, - { - "name": "organization", - "required": true, - "in": "path", - "schema": { - "type": "string" - } - } - ], - "get": { - "description": "Health check status and output for the given service group", - "responses": { - "200": { - "description": "Health Check - Ok / Warning", - "content": { - "application/json": { - "schema": { - "type": "object", - "x-amf-merge": [ - { - "$ref": "#/components/schemas/healthCheckOutput" - } - ] - } - } - } - }, - "404": { - "description": "Service not loaded" - }, - "500": { - "description": "Health Check - Unknown" - }, - "503": { - "description": "Health Check - Critical" - } - } - } - } - }, - "components": { - "schemas": { - "hookTable": { - "type": "object", - "properties": { - "health_check": { - "type": "object", - "x-amf-merge": [ - { - "$ref": "#/components/schemas/hookInfo" - } - ] - }, - "init": { - "type": "object", - "x-amf-merge": [ - { - "$ref": "#/components/schemas/hookInfo" - } - ] - }, - "file_updated": { - "type": "object", - "x-amf-merge": [ - { - "$ref": "#/components/schemas/hookInfo" - } - ] - }, - "reload": { - "type": "object", - "x-amf-merge": [ - { - "$ref": "#/components/schemas/hookInfo" - } - ] - }, - "reconfigure": { - "type": "object", - "x-amf-merge": [ - { - "$ref": "#/components/schemas/hookInfo" - } - ] - }, - "suitability": { - "type": "object", - "x-amf-merge": [ - { - "$ref": "#/components/schemas/hookInfo" - } - ] - }, - "run": { - "type": "object", - "x-amf-merge": [ - { - "$ref": "#/components/schemas/hookInfo" - } - ] - }, - "post_run": { - "type": "object", - "x-amf-merge": [ - { - "$ref": "#/components/schemas/hookInfo" - } - ] - } - } - }, - "pkg": { - "type": "object", - "required": [ - "ident", - "origin", - "name", - "version", - "release", - "deps", - "env", - "exposes", - "exports", - "path", - "svc_path", - "svc_config_path", - "svc_data_path", - "svc_files_path", - "svc_static_path", - "svc_var_path", - "svc_pid_file", - "svc_run", - "svc_user", - "svc_group" - ], - "properties": { - "ident": { - "type": "string" - }, - "origin": { - "type": "string" - }, - "name": { - "type": "string" - }, - "version": { - "type": "string" - }, - "release": { - "type": "string" - }, - "deps": { - "type": "array", - "x-amf-merge": [ - { - "type": "array", - "items": { - "$ref": "#/components/schemas/pkgIdent" - } - } - ] - }, - "env": { - "type": "object" - }, - "exposes": { - "type": "array", - "x-amf-merge": [ - { - "type": "array", - "items": { - "type": "string" - } - } - ] - }, - "exports": { - "type": "object" - }, - "path": { - "type": "string" - }, - "svc_path": { - "type": "string" - }, - "svc_config_path": { - "type": "string" - }, - "svc_data_path": { - "type": "string" - }, - "svc_files_path": { - "type": "string" - }, - "svc_static_path": { - "type": "string" - }, - "svc_var_path": { - "type": "string" - }, - "svc_pid_file": { - "type": "string" - }, - "svc_run": { - "type": "string" - }, - "svc_user": { - "type": "string" - }, - "svc_group": { - "type": "string" - } - } - }, - "processInfo": { - "type": "object", - "required": [ - "pid", - "preamble", - "state", - "state_entered", - "started" - ], - "properties": { - "pid": { - "type": "integer" - }, - "preamble": { - "type": "string" - }, - "state": { - "enum": [ - "Up", - "Down", - "Start", - "Restart" - ], - "type": "string" - }, - "state_entered": { - "type": "integer" - }, - "started": { - "type": "boolean" - } - } - }, - "service": { - "type": "object", - "required": [ - "service_group", - "bldr_url", - "spec_file", - "spec_ident", - "topology", - "update_strategy", - "cfg", - "pkg", - "sys", - "health_check", - "initialized", - "last_election_status", - "needs_reload", - "needs_reconfiguration", - "hooks", - "process" - ], - "properties": { - "service_group": { - "type": "string" - }, - "bldr_url": { - "type": "string" - }, - "spec_file": { - "type": "string" - }, - "spec_ident": { - "type": "object", - "x-amf-merge": [ - { - "$ref": "#/components/schemas/pkgIdent" - } - ] - }, - "topology": { - "enum": [ - "standalone", - "leader" - ], - "type": "string" - }, - "update_strategy": { - "enum": [ - "none", - "rolling", - "at-once" - ], - "type": "string" - }, - "cfg": { - "type": "object" - }, - "pkg": { - "type": "object", - "x-amf-merge": [ - { - "$ref": "#/components/schemas/pkg" - } - ] - }, - "sys": {}, - "health_check": { - "enum": [ - "Ok", - "Warning", - "Critical", - "Unknown" - ], - "type": "string" - }, - "initialized": { - "type": "boolean" - }, - "last_election_status": { - "type": "string" - }, - "needs_reload": { - "type": "boolean" - }, - "needs_reconfiguration": { - "type": "boolean" - }, - "hooks": { - "type": "object", - "x-amf-merge": [ - { - "$ref": "#/components/schemas/hookTable" - } - ] - }, - "config_from": { - "type": "string" - }, - "process": { - "type": "object", - "x-amf-merge": [ - { - "$ref": "#/components/schemas/processInfo" - } - ] - } - } - }, - "systemInfo": { - "type": "object", - "required": [ - "version", - "member_id", - "ip", - "hostname", - "gossip_ip", - "gossip_port", - "http_gateway_ip", - "http_gateway_port", - "permanent" - ], - "properties": { - "version": { - "type": "string" - }, - "member_id": { - "type": "string" - }, - "ip": { - "type": "string" - }, - "hostname": { - "type": "string" - }, - "gossip_ip": { - "type": "string" - }, - "gossip_port": { - "type": "integer" - }, - "http_gateway_ip": { - "type": "string" - }, - "http_gateway_port": { - "type": "integer" - }, - "permanent": { - "type": "boolean" - } - } - }, - "hookInfo": { - "type": "object", - "required": [ - "render_pair", - "stdout_log_path", - "stderr_log_path" - ], - "properties": { - "render_pair": { - "type": "string" - }, - "stdout_log_path": { - "type": "string" - }, - "stderr_log_path": { - "type": "string" - } - } - }, - "pkgIdent": { - "type": "object", - "required": [ - "origin", - "name" - ], - "properties": { - "origin": { - "type": "string" - }, - "name": { - "type": "string" - }, - "version": { - "type": "string" - }, - "release": { - "type": "integer" - } - } - }, - "healthCheckOutput": { - "type": "object", - "required": [ - "stdout", - "stderr" - ], - "properties": { - "stdout": { - "type": "string" - }, - "stderr": { - "type": "string" - } - } - } - } - } -} diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/authorize.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/authorize.png deleted file mode 100644 index 4c5dae8b20..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/authorize.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/build-job-view.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/build-job-view.png deleted file mode 100644 index e10c8ccc83..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/build-job-view.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/builder-build-latest-version.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/builder-build-latest-version.png deleted file mode 100644 index f68403ecd1..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/builder-build-latest-version.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/builder-key-upload.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/builder-key-upload.png deleted file mode 100644 index 3c3adcd176..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/builder-key-upload.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/builder-view-build-job-icon.svg b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/builder-view-build-job-icon.svg deleted file mode 100644 index 766c0bdd97..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/builder-view-build-job-icon.svg +++ /dev/null @@ -1,6 +0,0 @@ - - - - - - diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/builder_origin_members.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/builder_origin_members.png deleted file mode 100644 index eca841809c..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/builder_origin_members.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/builder_profile.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/builder_profile.png deleted file mode 100644 index 489384437b..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/builder_profile.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/builder_profile_user.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/builder_profile_user.png deleted file mode 100644 index bb2ef2a3b4..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/builder_profile_user.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/builder_signin.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/builder_signin.png deleted file mode 100644 index 2c64c0cb3e..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/builder_signin.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/connect-plan-builder.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/connect-plan-builder.png deleted file mode 100644 index 7fc62f3631..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/connect-plan-builder.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/create-origin-form.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/create-origin-form.png deleted file mode 100644 index 832c4cc40e..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/create-origin-form.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/create-origin.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/create-origin.png deleted file mode 100644 index bc3250bec1..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/create-origin.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/demo-tutorial-thumb.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/demo-tutorial-thumb.png deleted file mode 100644 index bee363a9eb..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/demo-tutorial-thumb.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/deploy-services-to-kubernetes-with-habitat-flow.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/deploy-services-to-kubernetes-with-habitat-flow.png deleted file mode 100644 index 7c2f500810..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/deploy-services-to-kubernetes-with-habitat-flow.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/environment_variable.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/environment_variable.png deleted file mode 100644 index 8b4c5ae83a..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/environment_variable.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/environment_variable_echo.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/environment_variable_echo.png deleted file mode 100644 index 12a6f0a80a..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/environment_variable_echo.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/environment_variable_new.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/environment_variable_new.png deleted file mode 100644 index c6a688d6cf..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/environment_variable_new.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/environment_variable_new_var.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/environment_variable_new_var.png deleted file mode 100644 index b014f9b462..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/environment_variable_new_var.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/environment_variable_set.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/environment_variable_set.png deleted file mode 100644 index f87a739f41..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/environment_variable_set.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/exports_callout.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/exports_callout.png deleted file mode 100644 index dcedc8a46e..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/exports_callout.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/hab-setup-complete.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/hab-setup-complete.png deleted file mode 100644 index 3e8e07b0f5..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/hab-setup-complete.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/hab-setup.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/hab-setup.png deleted file mode 100644 index 1c3ae67e9f..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/hab-setup.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-and-kubernetes-three-tiers-of-service-deployment.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-and-kubernetes-three-tiers-of-service-deployment.png deleted file mode 100644 index e0b1a1838a..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-and-kubernetes-three-tiers-of-service-deployment.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-application-rebuild-flow.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-application-rebuild-flow.png deleted file mode 100644 index b6e308c66b..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-application-rebuild-flow.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-architecture-overview.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-architecture-overview.png deleted file mode 100644 index f89d5c245b..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-architecture-overview.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-automated-docker-container-publishing-flow.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-automated-docker-container-publishing-flow.png deleted file mode 100644 index 6e360f219a..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-automated-docker-container-publishing-flow.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-builder-architecture.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-builder-architecture.png deleted file mode 100644 index e0a7d83128..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-builder-architecture.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-dependency-update-flow.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-dependency-update-flow.png deleted file mode 100644 index 58fbcf16c9..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-dependency-update-flow.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-diagrams-thumb.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-diagrams-thumb.png deleted file mode 100644 index 8c20094e6c..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-diagrams-thumb.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-initial-docker-container-publishing-flow.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-initial-docker-container-publishing-flow.png deleted file mode 100644 index 3e2d5c682c..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-initial-docker-container-publishing-flow.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-initial-package-build-flow.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-initial-package-build-flow.png deleted file mode 100644 index 6417f34f7a..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-initial-package-build-flow.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-logo.svg b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-logo.svg deleted file mode 100644 index 944865a125..0000000000 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-logo.svg +++ /dev/null @@ -1 +0,0 @@ -Chef Habitat \ No newline at end of file diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-on-premises-builder-depot-flow.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-on-premises-builder-depot-flow.png deleted file mode 100644 index 7645bc898f..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-on-premises-builder-depot-flow.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-promote-packages-through-channels.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-promote-packages-through-channels.png deleted file mode 100644 index ce49470411..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-promote-packages-through-channels.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-runtime-service-group-binding.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-runtime-service-group-binding.png deleted file mode 100644 index 139fd4649a..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/habitat-runtime-service-group-binding.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/mesos1-services-marathon.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/mesos1-services-marathon.png deleted file mode 100644 index f41cc6b744..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/mesos1-services-marathon.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/mesos2-new-application.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/mesos2-new-application.png deleted file mode 100644 index 61b998f588..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/mesos2-new-application.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/mesos3-new-application-json.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/mesos3-new-application-json.png deleted file mode 100644 index 4e330f8258..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/mesos3-new-application-json.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/mesos4-application.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/mesos4-application.png deleted file mode 100644 index 14f2e968fe..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/mesos4-application.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/mesos5-debugging.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/mesos5-debugging.png deleted file mode 100644 index e2e1e45b18..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/mesos5-debugging.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/origin-key-download.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/origin-key-download.png deleted file mode 100644 index ccf2266455..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/origin-key-download.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/origin-members.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/origin-members.png deleted file mode 100644 index 95c60368f4..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/origin-members.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/profile.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/profile.png deleted file mode 100644 index f0580c05f1..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/profile.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/supervisor_a_after.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/supervisor_a_after.png deleted file mode 100644 index abc6ab5e83..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/supervisor_a_after.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/supervisor_a_before.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/supervisor_a_before.png deleted file mode 100644 index e9e077f937..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/supervisor_a_before.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/supervisor_b_after.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/supervisor_b_after.png deleted file mode 100644 index 7b674faccb..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/supervisor_b_after.png and /dev/null differ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/supervisor_b_before.png b/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/supervisor_b_before.png deleted file mode 100644 index 8ccb76b490..0000000000 Binary files a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/supervisor_b_before.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 deleted file mode 100644 index 4a689b4204..0000000000 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/config.toml +++ /dev/null @@ -1,2 +0,0 @@ -[params.on-prem-builder] -gh_path = "https://github.com/habitat-sh/on-prem-builder/tree/main/docs-chef-io/content/" diff --git a/_vendor/modules.txt b/_vendor/modules.txt index efea8a32fd..43cc3fb3eb 100644 --- a/_vendor/modules.txt +++ b/_vendor/modules.txt @@ -1,7 +1,5 @@ # github.com/chef/automate/components/docs-chef-io v0.0.0-20251106140316-cca3ad103bd3 # 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-20250905124722-c1a4eb639cba -# github.com/habitat-sh/on-prem-builder/docs-chef-io v0.0.0-20250805192817-f8b1dae05d5e # github.com/chef/chef-server/docs-chef-io v0.0.0-20251103154204-52161ef2177d # github.com/chef/chef-workstation/docs-chef-io v0.0.0-20250930142111-8c07fe8a2202 # github.com/chef/supermarket/docs-chef-io v0.0.0-20250602140848-cded623a3f5c diff --git a/config/_default/menu.toml b/config/_default/menu.toml index d6da6afb85..05f6b11b62 100644 --- a/config/_default/menu.toml +++ b/config/_default/menu.toml @@ -392,103 +392,68 @@ title = "Chef Habitat" identifier = "habitat" [[habitat]] - title = "Install Habitat" - identifier = "habitat/install" + title = "Habitat v 2.0" parent = "habitat" - weight = 15 + identifier = "habitat/2.0" + url = "/habitat/2.0/" + weight = 10 [[habitat]] - title = "SaaS Builder" - identifier = "habitat/builder" + title = "Habitat v 1.6" parent = "habitat" - weight = 20 + identifier = "habitat/1.6" + url = "/habitat/1.6/" + weight = 10 [[habitat]] - title = "On-Prem Builder" - identifier = "habitat/on-prem-builder" + title = "Habitat Builder" + identifier = "habitat/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 + weight = 20 [[habitat]] - title = "Origins" - identifier = "habitat/on-prem-builder/origins" - parent = "habitat/on-prem-builder" - weight = 50 + title = "SaaS Builder" + identifier = "habitat/builder/saas" + parent = "habitat/builder" [[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 + title = "On-Prem Builder" + identifier = "habitat/builder/on-prem" + parent = "habitat/builder" + + [[habitat]] + title = "Install" + identifier = "habitat/builder/on-prem/install" + parent = "habitat/builder/on-prem" + weight = 20 - [[habitat]] - title = "Supervisors" - identifier = "habitat/supervisors" - parent = "habitat" - weight = 80 + [[habitat]] + title = "Configure" + identifier = "habitat/builder/on-prem/configure" + parent = "habitat/builder/on-prem" + weight = 30 - [[habitat]] - title = "Reference" - identifier = "habitat/reference" - parent = "habitat" - weight = 90 + [[habitat]] + title = "Manage" + identifier = "habitat/builder/on-prem/manage" + parent = "habitat/builder/on-prem" + weight = 40 - [[habitat]] - title = "API" - identifier = "habitat/reference/api" - parent = "habitat/reference" + [[habitat]] + title = "Origins" + identifier = "habitat/builder/on-prem/origins" + parent = "habitat/builder/on-prem" + weight = 50 - [[habitat]] - title = "Containers" - identifier = "habitat/containers" - parent = "habitat" - weight = 200 + [[habitat]] + title = "Packages" + identifier = "habitat/builder/on-prem/packages" + parent = "habitat/builder/on-prem" + weight = 60 [[habitat]] - title = "Diagrams" - identifier = "habitat/diagrams" + title = "Supported packages" + identifier = "habitat/supported_packages" parent = "habitat" weight = 500 diff --git a/config/_default/module.toml b/config/_default/module.toml index 50fdd3d3c6..364f00a652 100644 --- a/config/_default/module.toml +++ b/config/_default/module.toml @@ -58,43 +58,22 @@ workspace = '' source = "layouts" target = "layouts" -### -# Chef Habitat -### - -[[imports]] - disable = false - ignoreConfig = false - path = "github.com/habitat-sh/habitat/components/docs-chef-io" - -[[imports.mounts]] - source = "content/habitat" - target = "content/habitat" - -[[imports.mounts]] - source = "static" - target = "static" - -[[imports.mounts]] - 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]] +# disable = false +# ignoreConfig = false +# path = "github.com/habitat-sh/on-prem-builder/docs-chef-io" -[[imports.mounts]] - source = "content" - target = "content" +# [[imports.mounts]] +# source = "content/habitat/on_prem_builder" +# target = "content/habitat/builder/on_prem" -[[imports.mounts]] - source = "static" - target = "assets" +# [[imports.mounts]] +# source = "static" +# target = "assets" ### # Chef Infra Server diff --git a/config/_default/params.toml b/config/_default/params.toml index 95b267b0b0..2f21f12349 100644 --- a/config/_default/params.toml +++ b/config/_default/params.toml @@ -70,7 +70,7 @@ gh_path = "https://github.com/chef/license-service/tree/main/docs-chef-io/conten [search] -default_search_product_keys = ["", "chef-360-saas", "chef-360-1.5", "automate", "desktop", "habitat", "client", "server", "inspec", "inspec-7.0", "saas", "supermarket", "workstation"] +default_search_product_keys = ["", "chef-360-saas", "chef-360-1.5", "automate", "desktop", "habitat", "habitat-2.0", "client", "server", "inspec", "inspec-7.0", "saas", "supermarket", "workstation"] [search.products] @@ -118,6 +118,14 @@ product_key = "desktop" name = "Habitat" product_key = "habitat" +[[search.products.habitat.versions]] +name = "2.0" +product_version_key = "habitat-2.0" + +[[search.products.habitat.versions]] +name = "1.6" +product_version_key = "habitat-1.6" + [search.products.infra_client] name = "Infra Client" product_key = "client" diff --git a/content/habitat/_index.md b/content/habitat/_index.md new file mode 100644 index 0000000000..f75a2eb0ab --- /dev/null +++ b/content/habitat/_index.md @@ -0,0 +1,14 @@ ++++ +title = "Chef Habitat" + ++++ + +## Chef Habitat releases + +- [Chef Habitat v 2.0](/habitat/2.0/) +- [Chef Habitat v 1.6](/habitat/1.6/) + +## Chef Habitat Builder + +- [Chef Habitat On-Prem Builder](/builder/on_prem/) +- [Chef Habitat SaaS Builder](/builder/saas/) diff --git a/content/habitat/about_services.md b/content/habitat/about_services.md new file mode 100644 index 0000000000..e7adfabf94 --- /dev/null +++ b/content/habitat/about_services.md @@ -0,0 +1,4 @@ ++++ +layout = "redirect" +redirect_url = "https://docs.chef.io/habitat/latest/services/" ++++ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_overview.md b/content/habitat/builder/_index.md similarity index 61% rename from _vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_overview.md rename to content/habitat/builder/_index.md index be63533f56..6d2535f73c 100644 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_overview.md +++ b/content/habitat/builder/_index.md @@ -1,30 +1,29 @@ +++ title = "About Chef Habitat Builder" description = "Chef Habitat Builder is Chef's Application Delivery Enterprise hub" -gh_repo = "habitat" -aliases = ["/habitat/using-builder/"] +linkTitle = "Builder" +summary = "Chef Habitat Builder is Chef's Application Delivery Enterprise hub" +list_pages = true -[menu] - [menu.habitat] - title = "Chef Habitat Builder" - identifier = "habitat/builder/builder" +[menu.habitat] + title = "About Habitat Builder" + identifier = "habitat/builder/about" parent = "habitat/builder" weight = 10 +++ -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 acts as the core of Chef's Application Delivery Enterprise hub. +It provides a repository for all available Chef Habitat packages built by Chef and the supporting community, as well as search and an API for clients. + +You can store application plans on the Chef Habitat Builder SaaS where the Chef Habitat community can view and access them. You can also deploy the [on-prem version of Chef Habitat Builder](https://github.com/habitat-sh/on-prem-builder) where you can store and maintain your apps in a secure environment. ## 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 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. +- **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 upgraded automatically 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 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). +For more information about how the SaaS and on-premises versions of Chef Habitat Builder work together, read the blog: [Chef Habitat On-Prem Builder 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/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/_index.md b/content/habitat/builder/on_prem/_index.md similarity index 80% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/_index.md rename to content/habitat/builder/on_prem/_index.md index ef4a2eb077..5a0bfa8ca9 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/_index.md +++ b/content/habitat/builder/on_prem/_index.md @@ -1,16 +1,14 @@ +++ title = "About Chef Habitat On-Prem Builder" - -[cascade] - [cascade.params] - gh_repo = "on-prem-builder" - product = ["habitat"] +description = "Chef Habitat Builder is Chef's Application Delivery Enterprise hub" +linkTitle = "Habitat On-Prem Builder" +summary = "Host and manage packages within your organization's infrastructure" [menu] [menu.habitat] title = "About On-Prem Builder" - identifier = "habitat/on-prem-builder/overview" - parent = "habitat/on-prem-builder" + identifier = "habitat/builder/on-prem/about" + parent = "habitat/builder/on-prem" weight = 10 +++ @@ -22,7 +20,7 @@ You can direct Chef Habitat clients (such as the `hab` cli, Supervisors, and Stu ## Audience -This documentation is for anyone who wishes to host Chef Habitat packages in their own infrastructure. +This documentation is for anyone who wants to host Chef Habitat packages in their own infrastructure. ## Features @@ -52,5 +50,5 @@ The following Chef Habitat SaaS Builder features aren't available with On-Prem B ## More information -- [Chef Habitat CLI](/habitat/habitat_cli/) +- [Chef Habitat CLI](/habitat/latest/reference/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/static/images/habitat/on_prem_builder/builder_architecture.png b/content/habitat/builder/on_prem/builder_architecture.png similarity index 100% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/static/images/habitat/on_prem_builder/builder_architecture.png rename to content/habitat/builder/on_prem/builder_architecture.png diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/_index.md b/content/habitat/builder/on_prem/configure/_index.md similarity index 85% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/_index.md rename to content/habitat/builder/on_prem/configure/_index.md index a57ccfe0e2..a406d95222 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/_index.md +++ b/content/habitat/builder/on_prem/configure/_index.md @@ -4,8 +4,8 @@ title = "Chef Habitat On-Prem Builder" [menu] [menu.habitat] title = "Overview" - identifier = "habitat/on-prem-builder/configure/overview" - parent = "habitat/on-prem-builder/configure" + identifier = "habitat/builder/on-prem/configure/overview" + parent = "habitat/builder/on-prem/configure" weight = 10 +++ diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/artifactory.md b/content/habitat/builder/on_prem/configure/artifactory.md similarity index 94% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/artifactory.md rename to content/habitat/builder/on_prem/configure/artifactory.md index ae386fb6de..b89044c1f3 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/artifactory.md +++ b/content/habitat/builder/on_prem/configure/artifactory.md @@ -4,8 +4,8 @@ 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" + identifier = "habitat/builder/on-prem/configure/artifactory" + parent = "habitat/builder/on-prem/configure" weight = 30 +++ 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/content/habitat/builder/on_prem/configure/builder_config_example.md similarity index 97% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/builder_config_example.md rename to content/habitat/builder/on_prem/configure/builder_config_example.md index 5a1f1ba1da..3e9bedf15f 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/builder_config_example.md +++ b/content/habitat/builder/on_prem/configure/builder_config_example.md @@ -4,8 +4,8 @@ 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" + identifier = "habitat/builder/on-prem/configure/builder.env" + parent = "habitat/builder/on-prem/configure" weight = 20 +++ 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/content/habitat/builder/on_prem/configure/disaster_recovery_warm_spare.md similarity index 89% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/disaster_recovery_warm_spare.md rename to content/habitat/builder/on_prem/configure/disaster_recovery_warm_spare.md index 51cf552ea6..324478df79 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/disaster_recovery_warm_spare.md +++ b/content/habitat/builder/on_prem/configure/disaster_recovery_warm_spare.md @@ -4,8 +4,8 @@ title = "Configure Chef Habitat On-Prem Builder for disaster recovery or a warm [menu] [menu.habitat] title = "Configure disaster recovery or warm spare" - identifier = "habitat/on-prem-builder/configure/disaster recovery" - parent = "habitat/on-prem-builder/configure" + identifier = "habitat/builder/on-prem/configure/disaster recovery" + parent = "habitat/builder/on-prem/configure" weight = 30 +++ @@ -14,13 +14,13 @@ To quickly recover from an outage or perform planned upgrades or maintenance, yo ## 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. +There's 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) +![Habitat On-Prem Builder's architecture](/habitat/builder/on_prem/builder_architecture.png) ### Synchronize components @@ -63,7 +63,7 @@ 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. +If your backend uses MinIO for artifact storage, make sure it's 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. diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/logs.md b/content/habitat/builder/on_prem/configure/logs.md similarity index 95% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/logs.md rename to content/habitat/builder/on_prem/configure/logs.md index fb99d2da5b..6719848b4c 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/logs.md +++ b/content/habitat/builder/on_prem/configure/logs.md @@ -4,8 +4,8 @@ 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" + identifier = "habitat/builder/on-prem/configure/logs" + parent = "habitat/builder/on-prem/configure" weight = 40 +++ 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/content/habitat/builder/on_prem/configure/scale_frontend_nodes.md similarity index 95% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/scale_frontend_nodes.md rename to content/habitat/builder/on_prem/configure/scale_frontend_nodes.md index 52d5989afd..b686f6383b 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/scale_frontend_nodes.md +++ b/content/habitat/builder/on_prem/configure/scale_frontend_nodes.md @@ -4,8 +4,8 @@ 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" + identifier = "habitat/builder/on-prem/configure/frontend scaling" + parent = "habitat/builder/on-prem/configure" weight = 50 +++ @@ -56,7 +56,7 @@ Because Habitat Builder services need to communicate across your network between ## 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. +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 during 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). 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/content/habitat/builder/on_prem/configure/separate_backend_services.md similarity index 97% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/separate_backend_services.md rename to content/habitat/builder/on_prem/configure/separate_backend_services.md index aeb71dbf16..a903be7c65 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/configure/separate_backend_services.md +++ b/content/habitat/builder/on_prem/configure/separate_backend_services.md @@ -4,8 +4,8 @@ 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" + identifier = "habitat/builder/on-prem/configure/Separating backend services" + parent = "habitat/builder/on-prem/configure" weight = 60 +++ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/create-origin-done.png b/content/habitat/builder/on_prem/create-origin-done.png similarity index 100% rename from _vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/create-origin-done.png rename to content/habitat/builder/on_prem/create-origin-done.png diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/install/_index.md b/content/habitat/builder/on_prem/install/_index.md similarity index 81% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/install/_index.md rename to content/habitat/builder/on_prem/install/_index.md index 35d116ee48..a558315e11 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/install/_index.md +++ b/content/habitat/builder/on_prem/install/_index.md @@ -4,8 +4,8 @@ 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" + identifier = "habitat/builder/on-prem/install/install/overview" + parent = "habitat/builder/on-prem/install" weight = 10 +++ @@ -19,7 +19,7 @@ Before you begin, review the [Habitat Builder system requirements](system_requir To deploy Habitat On-Prem Builder, use the following guide: -- [Install Habitat On-Prem Builder authenticating with another OAuth service](builder-oauth) +- [Install Habitat On-Prem Builder authenticating with another OAuth service](builder_oauth) ## Workstation configuration diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/install/builder_oauth.md b/content/habitat/builder/on_prem/install/builder_oauth.md similarity index 98% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/install/builder_oauth.md rename to content/habitat/builder/on_prem/install/builder_oauth.md index 0d12085851..d06da507dc 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/install/builder_oauth.md +++ b/content/habitat/builder/on_prem/install/builder_oauth.md @@ -4,8 +4,8 @@ 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" + identifier = "habitat/builder/on-prem/install/o-auth" + parent = "habitat/builder/on-prem/install" weight = 40 +++ diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/install/system_requirements.md b/content/habitat/builder/on_prem/install/system_requirements.md similarity index 95% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/install/system_requirements.md rename to content/habitat/builder/on_prem/install/system_requirements.md index 04757c3bd8..d70cb1024b 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/install/system_requirements.md +++ b/content/habitat/builder/on_prem/install/system_requirements.md @@ -4,8 +4,8 @@ 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" + identifier = "habitat/builder/on-prem/install/install/system requirements" + parent = "habitat/builder/on-prem/install" weight = 20 +++ diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/install/workstation.md b/content/habitat/builder/on_prem/install/workstation.md similarity index 92% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/install/workstation.md rename to content/habitat/builder/on_prem/install/workstation.md index faa85685af..0a6b01dcc2 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/install/workstation.md +++ b/content/habitat/builder/on_prem/install/workstation.md @@ -4,8 +4,8 @@ title = "Connect your workstation to your Chef Habitat On-Prem Builder deploymen [menu] [menu.habitat] title = "Connect your workstation to Builder" - identifier = "habitat/on-prem-builder/install/workstation" - parent = "habitat/on-prem-builder/install" + identifier = "habitat/builder/on-prem/install/workstation" + parent = "habitat/builder/on-prem/install" weight = 50 +++ diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/_index.md b/content/habitat/builder/on_prem/manage/_index.md similarity index 80% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/_index.md rename to content/habitat/builder/on_prem/manage/_index.md index afb52b7ace..6bc5e03e97 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/_index.md +++ b/content/habitat/builder/on_prem/manage/_index.md @@ -4,8 +4,8 @@ title = "Manage Habitat On-Prem Builder" [menu] [menu.habitat] title = "Overview" - identifier = "habitat/on-prem-builder/manage/overview" - parent = "habitat/on-prem-builder/manage" + identifier = "habitat/builder/on-prem/manage/overview" + parent = "habitat/builder/on-prem/manage" weight = 10 +++ diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/minio.md b/content/habitat/builder/on_prem/manage/minio.md similarity index 95% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/minio.md rename to content/habitat/builder/on_prem/manage/minio.md index 0addb49739..b982134758 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/minio.md +++ b/content/habitat/builder/on_prem/manage/minio.md @@ -4,8 +4,8 @@ title = "Manage your MinIO artifact store" [menu] [menu.habitat] title = "MinIO" - identifier = "habitat/on-prem-builder/manage/minio" - parent = "habitat/on-prem-builder/manage" + identifier = "habitat/builder/on-prem/manage/minio" + parent = "habitat/builder/on-prem/manage" weight = 20 +++ diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/postgres.md b/content/habitat/builder/on_prem/manage/postgres.md similarity index 96% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/postgres.md rename to content/habitat/builder/on_prem/manage/postgres.md index 2791ea0baa..3eaac6b996 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/postgres.md +++ b/content/habitat/builder/on_prem/manage/postgres.md @@ -4,11 +4,13 @@ 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" + identifier = "habitat/builder/on-prem/manage/PostgreSQL" + parent = "habitat/builder/on-prem/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 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/content/habitat/builder/on_prem/manage/ssl_cert_rotation.md similarity index 93% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/ssl_cert_rotation.md rename to content/habitat/builder/on_prem/manage/ssl_cert_rotation.md index 58198736a5..0898267439 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/ssl_cert_rotation.md +++ b/content/habitat/builder/on_prem/manage/ssl_cert_rotation.md @@ -3,8 +3,8 @@ 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" + identifier = "habitat/builder/on-prem/manage/SSL certs" + parent = "habitat/builder/on-prem/manage" weight = 40 +++ diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/upgrade.md b/content/habitat/builder/on_prem/manage/upgrade.md similarity index 91% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/upgrade.md rename to content/habitat/builder/on_prem/manage/upgrade.md index 616410c0c7..b988893d0b 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/manage/upgrade.md +++ b/content/habitat/builder/on_prem/manage/upgrade.md @@ -4,8 +4,8 @@ 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" + identifier = "habitat/builder/on-prem/manage/upgrade" + parent = "habitat/builder/on-prem/manage" weight = 50 +++ diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/origin-keys.png b/content/habitat/builder/on_prem/origin-keys.png similarity index 100% rename from _vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/origin-keys.png rename to content/habitat/builder/on_prem/origin-keys.png diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/origin-secrets.png b/content/habitat/builder/on_prem/origin-secrets.png similarity index 100% rename from _vendor/github.com/habitat-sh/habitat/components/docs-chef-io/static/images/habitat/origin-secrets.png rename to content/habitat/builder/on_prem/origin-secrets.png diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/_index.md b/content/habitat/builder/on_prem/origins/_index.md similarity index 93% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/_index.md rename to content/habitat/builder/on_prem/origins/_index.md index add4208a14..3d2eb4a51e 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/_index.md +++ b/content/habitat/builder/on_prem/origins/_index.md @@ -4,8 +4,8 @@ title = "Chef Habitat origins" [menu] [menu.habitat] title = "Overview" - identifier = "habitat/on-prem-builder/origins/overview" - parent = "habitat/on-prem-builder/origins" + identifier = "habitat/builder/on-prem/origins/overview" + parent = "habitat/builder/on-prem/origins" weight = 10 +++ 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/content/habitat/builder/on_prem/origins/create_an_origin.md similarity index 91% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/create_an_origin.md rename to content/habitat/builder/on_prem/origins/create_an_origin.md index 0f0fccc210..c8e3e579ad 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/create_an_origin.md +++ b/content/habitat/builder/on_prem/origins/create_an_origin.md @@ -4,8 +4,8 @@ title = "Create an origin" [menu] [menu.habitat] title = "Create an origin" - identifier = "habitat/on-prem-builder/origins/create" - parent = "habitat/on-prem-builder/origins" + identifier = "habitat/builder/on-prem/origins/create" + parent = "habitat/builder/on-prem/origins" weight = 20 +++ @@ -37,7 +37,7 @@ To create an origin in your Chef Habitat Builder deployment, follow these steps: - Creates an [origin key pair](../origin_keys). - Redirects you to the origin page. - ![Origin successfully created](/images/habitat/create-origin-done.png) + ![Origin successfully created](/habitat/builder/on_prem/create-origin-done.png) ## Create an origin with the Chef Habitat CLI diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/origin_keys.md b/content/habitat/builder/on_prem/origins/origin_keys.md similarity index 96% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/origin_keys.md rename to content/habitat/builder/on_prem/origins/origin_keys.md index fa70f8032d..fa9cae795b 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/origin_keys.md +++ b/content/habitat/builder/on_prem/origins/origin_keys.md @@ -4,8 +4,8 @@ title = "Habitat origin keys" [menu] [menu.habitat] title = "Origin keys" - identifier = "habitat/on-prem-builder/origins/keys" - parent = "habitat/on-prem-builder/origins" + identifier = "habitat/builder/on-prem/origins/keys" + parent = "habitat/builder/on-prem/origins" weight = 30 +++ @@ -59,7 +59,7 @@ testorigin-20190416223046.sig.key 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) +![Viewing your origin keys](/habitat/builder/on_prem/origin-keys.png) ### Download origin keys @@ -132,7 +132,7 @@ 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. +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 doesn't 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. diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/origin_settings.md b/content/habitat/builder/on_prem/origins/origin_settings.md similarity index 96% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/origin_settings.md rename to content/habitat/builder/on_prem/origins/origin_settings.md index a094bae467..08655a350c 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/origin_settings.md +++ b/content/habitat/builder/on_prem/origins/origin_settings.md @@ -4,8 +4,8 @@ title = "Habitat origin settings" [menu] [menu.habitat] title = "Origin settings" - identifier = "habitat/on-prem-builder/origins/settings" - parent = "habitat/on-prem-builder/origins" + identifier = "habitat/builder/on-prem/origins/settings" + parent = "habitat/builder/on-prem/origins" weight = 40 +++ @@ -20,7 +20,7 @@ Every origin member can view the origin's settings, but only origin administrato | 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) +![The administrator or owner's view of the origin settings tab with a public default package setting and a saved origin secret](/habitat/builder/on_prem/origin-secrets.png) ## Default package settings diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/rbac.md b/content/habitat/builder/on_prem/origins/rbac.md similarity index 98% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/rbac.md rename to content/habitat/builder/on_prem/origins/rbac.md index 7a489c6658..383508a851 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/origins/rbac.md +++ b/content/habitat/builder/on_prem/origins/rbac.md @@ -4,8 +4,8 @@ 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" + identifier = "habitat/builder/on-prem/origins/rbac" + parent = "habitat/builder/on-prem/origins" weight = 50 +++ diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/packages/_index.md b/content/habitat/builder/on_prem/packages/_index.md similarity index 75% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/packages/_index.md rename to content/habitat/builder/on_prem/packages/_index.md index 14ed45f818..192dc6d5cf 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/packages/_index.md +++ b/content/habitat/builder/on_prem/packages/_index.md @@ -4,8 +4,8 @@ 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" + identifier = "habitat/builder/on-prem/packages/overview" + parent = "habitat/builder/on-prem/packages" weight = 10 +++ 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/content/habitat/builder/on_prem/packages/bootstrap_core_packages.md similarity index 97% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/packages/bootstrap_core_packages.md rename to content/habitat/builder/on_prem/packages/bootstrap_core_packages.md index 06595cbe76..f0d324b256 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/packages/bootstrap_core_packages.md +++ b/content/habitat/builder/on_prem/packages/bootstrap_core_packages.md @@ -4,8 +4,8 @@ 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" + identifier = "habitat/builder/on-prem/packages/Bootstrap Core Packages" + parent = "habitat/builder/on-prem/packages" weight = 20 +++ diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/packages/update_packages.md b/content/habitat/builder/on_prem/packages/update_packages.md similarity index 97% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/packages/update_packages.md rename to content/habitat/builder/on_prem/packages/update_packages.md index 5ac82e3b6f..136893699f 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/packages/update_packages.md +++ b/content/habitat/builder/on_prem/packages/update_packages.md @@ -4,8 +4,8 @@ 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" + identifier = "habitat/builder/on-prem/packages/update" + parent = "habitat/builder/on-prem/packages" weight = 30 +++ diff --git a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/troubleshooting.md b/content/habitat/builder/on_prem/troubleshooting.md similarity index 95% rename from _vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/troubleshooting.md rename to content/habitat/builder/on_prem/troubleshooting.md index 67e9a835e7..9809a97bb2 100644 --- a/_vendor/github.com/habitat-sh/on-prem-builder/docs-chef-io/content/habitat/on_prem_builder/troubleshooting.md +++ b/content/habitat/builder/on_prem/troubleshooting.md @@ -4,8 +4,8 @@ title = "Troubleshooting Chef Habitat On-Prem Builder" [menu] [menu.habitat] title = "Troubleshooting" - identifier = "habitat/on-prem-builder/troubleshooting" - parent = "habitat/on-prem-builder" + identifier = "habitat/builder/on-prem/troubleshooting" + parent = "habitat/builder/on-prem" weight = 500 +++ @@ -90,7 +90,7 @@ 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`. +- Name your certificate files using the pattern `-cert.cert` or `-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. @@ -211,7 +211,7 @@ HAB_CLIENT_SOCKET_TIMEOUT=360 hab pkg upload -u -z }}) -* A [GitHub account](https://github.com/join) +- download and install the [Chef Habitat CLI](/install/) +- a [GitHub account](https://github.com/join) +- a Progress Chef license -## 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. @@ -30,8 +31,8 @@ Head over to the Chef Habitat Builder sign-in page at [https://bldr.habitat.sh/# 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 -![Chef Habitat sign in with Github](/images/habitat/builder_signin.png) +![Chef Habitat sign in with Github](/images/habitat/builder_sign_in.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. -![Authorize the Chef Habitat Application](/images/habitat/authorize.png) +{{< figure src="/images/habitat/authorize.png" alt="Chef Habitat and GitHub authorization screen." width="500px" >}} \ No newline at end of file diff --git a/content/habitat/builder/saas/builder_api.md b/content/habitat/builder/saas/builder_api.md new file mode 100644 index 0000000000..89137e8f1f --- /dev/null +++ b/content/habitat/builder/saas/builder_api.md @@ -0,0 +1,16 @@ ++++ +title = "Chef Habitat Builder API" + +draft = false +layout = "data-api" + +api_file_path = "../builder-api.json" +return_page = "../" +description = "Chef Habitat Builder API documentation." +summary = "Habitat Builder OpenAPI specification" + +[menu.habitat] + title = "Builder API" + parent = "habitat/builder/saas" + identifier = "habitat/builder/saas/Builder API" ++++ diff --git a/content/habitat/builder/saas/builder_origin_packages.md b/content/habitat/builder/saas/builder_origin_packages.md new file mode 100644 index 0000000000..0f34646557 --- /dev/null +++ b/content/habitat/builder/saas/builder_origin_packages.md @@ -0,0 +1,121 @@ ++++ +title = "Upload and promote Habitat packages" +description = "Upload and Promote packages on Chef Habitat Builder enables automated package rebuilds and increases collaboration" +summary = "Upload and promote packages so you can automated package rebuilds and collaborate" + + +[menu.habitat] + title = "Origin packages" + identifier = "habitat/builder/saas/origin-packages" + parent = "habitat/builder/saas" + weight = 40 ++++ + +While you can build and run Chef Habitat packages without sharing them on [Chef Habitat Builder](https://bldr.habitat.sh), uploading them there enables greater collaboration and automated package rebuilds as underlying dependencies or your connected GitHub repository are updated. + +{{< note >}} + +Chef Habitat Builder can only build Linux-based plans (`plan.sh`) at this time. + +{{< /note >}} + +Setting up Chef Habitat Builder is easily done on the website: these steps take you through connecting your local Studio development experience with Builder. + +You interact with Chef Habitat Builder by: + +- Creating an account. +- Creating an origin, or being invited to join an origin that already exists. +- Setting up `hab` to authenticate with Builder. +- Uploading the private and public keys for that origin. +- Connecting your Github repositories and opting into rebuilds. + +Chef Habitat Builder supports both public and private origins, packages, and Github repositories. + +## Create a Builder account + +Before you begin, [Create a Builder account](builder_account). + +## Create or join an existing origin + +You can create your own origin in Builder or be invited to join an existing one. If you already built some Chef Habitat packages on your local computer prior to signing up for an account, you must rename your local packages' `pkg_origin` if the origin you want already exists. + +## Set up Chef Habitat to authenticate to Builder + +When you upload a package to Builder, you are required to supply an auth token as part of the `hab pkg upload` subcommand. You can generate a Chef Habitat personal access token with the Builder site [Profile page](https://bldr.habitat.sh/#/profile) for use with the `hab` command-line utility. + +Once you have this token, you can set the `HAB_AUTH_TOKEN` [environment variable](/reference/environment_variables.md) to this value, so that any commands requiring authentication will use it. + +## Create an origin key pair + +After finishing the basic account creation steps, you need to create your origin key pair. Habitat will use the private origin key to sign the artifacts (`.hart` files) created by building your plan and verify the integrity of your artifacts with the public origin key. + +You can create an origin key pair by running `hab cli setup` from your host machine, or by running `hab origin key generate ` from either the host machine or from within the studio. + +Your public and private origin keys are located at `~/.hab/cache/keys` on your host machine and at `/hab/cache/keys` inside the studio environment. + +## Upload your origin keys + +If you created a new Habitat origin from your host machine or from the Studio, Builder won't have either of the origin keys corresponding to your artifact. Builder won't accept uploaded artifacts without first having the correct public origin key. + +You can upload keys for the origin through the web interface for Builder, or by using the `hab origin key upload` command. You must have the access token for authentication, as described earlier, before you can upload keys. + +## Upload packages to Builder + +As long as you are already a member of the Habitat origin, once Builder possesses at least the public origin key, then you may upload one or more artifacts to that origin with the `hab pkg upload` command. After Habitat validates the cryptographic integrity of the artifact, it's then uploaded and stored on Builder. Uploading artifacts is a privileged operation for which you must have the access token. + +## Promote packages + +By default, newly uploaded packages are placed in the `unstable` channel. However, the default package that's downloaded is the latest `stable` version of a package, unless overridden in commands such as `hab sup run`, `hab svc load`, and `hab pkg install`. If you want to promote your package to the `stable` channel, run the `hab pkg promote` command as follows: + +```bash +hab pkg promote -z origin/package/version/release stable +``` + +{{< note >}} + +You can also promote packages to the `stable` channel using the *promote to stable* button in the web app. + +{{< /note >}} + +For more information on how to use channels, see [Continuous Deployment Using Channels](/packages/pkg_promote.md). + +### Running packages from Builder + +{{< note >}} + +When running private packages from Builder, it's necessary to add your [Chef Habitat access token](builder_profile#create-a-personal-access-token) to the machine where you intend to deploy the package, with `export HAB_AUTH_TOKEN=`. + +{{< /note >}} + +You can instruct the Supervisor to download and run packages from Builder by using the `hab sup` and `hab svc` commands, for example: + +```bash +hab sup run +hab svc load core/postgresql +``` + +If the Supervisor doesn't have the `core/postgresql` package in its local cache, it will contact Builder, retrieve the latest version and the public key for the `core` origin, verify the cryptographic integrity of the package, and then start it. + +You may also supply a `--channel` argument to instruct the Supervisor to use a different channel for the purposes of continuous deployment: + +```bash +hab svc load core/postgresql --channel unstable +``` + +### Running packages from exported tarballs + +An exported tarball package contains the Chef Habitat client/binary as well as dependencies specified by your artifact. + +After deploying the tarball to your target server, extract the contents to the root filesystem (`/`): + +```bash +tar zxf core-nginx-1.11.10-20170616000025.tar.gz --directory / +``` + +You can instruct the Supervisor to run packages from an exported tarball: + +```bash +/hab/bin/hab svc start core/nginx +``` + +Note: On a clean server, this will download additional packages to satisfy the Supervisor dependencies. You will also require a `hab` group and `hab` user on the system for most services. diff --git a/content/habitat/builder/saas/builder_origins.md b/content/habitat/builder/saas/builder_origins.md new file mode 100644 index 0000000000..1fec45360b --- /dev/null +++ b/content/habitat/builder/saas/builder_origins.md @@ -0,0 +1,31 @@ ++++ +title = "Create an origin on Builder" +description = "Create an origin on Builder" + + +[menu.habitat] + title = "Origins" + identifier = "habitat/builder/saas/origins" + parent = "habitat/builder/saas" + weight = 30 ++++ + +An origin is a unique namespace in Chef Habitat Builder where you can store, share, and build packages. +Once created, an origin can't be renamed, but it can be deleted or transferred. +For example, the _core_ origin contains foundational packages managed and versioned by Chef Habitat maintainers. + +You can join existing origins by invitation or create your own origins in an on-prem Habitat Builder deployment. For details about invitations, see [origin membership and RBAC](origin_rbac#origin-membership" >}}). + +## 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 on-prem Habitat Builder deployment. + +## Where can I create an origin + +You can create origins with [Habitat On-Prem Builder](https://docs.chef.io/habitat/on_prem_builder/). +You can't create origins in [Chef's public Habitat SaaS Builder](https://bldr.habitat.sh). diff --git a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_profile.md b/content/habitat/builder/saas/builder_profile.md similarity index 92% rename from _vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_profile.md rename to content/habitat/builder/saas/builder_profile.md index 1437404203..959deec1c8 100644 --- a/_vendor/github.com/habitat-sh/habitat/components/docs-chef-io/content/habitat/builder_profile.md +++ b/content/habitat/builder/saas/builder_profile.md @@ -1,19 +1,15 @@ +++ -title = "Builder Profile" - -date = 2020-10-12T16:08:26-07:00 -draft = false -gh_repo = "habitat" - -[menu] - [menu.habitat] - title = "Builder Profile" - identifier = "habitat/builder/builder-profile Builder Profile" - parent = "habitat/builder" - weight = 30 +title = "Builder profile" + + +[menu.habitat] + title = "Builder profile" + identifier = "habitat/builder/saas/Builder Profile" + parent = "habitat/builder/saas" + weight = 30 +++ -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. +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 on-prem version, sync the two accounts. ## Get an account @@ -21,7 +17,7 @@ To use the SaaS or on-premises version of Chef Habitat Builder, you need to crea Set up the following before getting started with Chef Habitat Builder: -- Download and install the [Chef Habitat CLI]({{< relref "install_habitat" >}}) +- Download and install the [Chef Habitat CLI](/install/) - A [GitHub account](https://github.com/join) ### Sign in and authorize Chef Habitat Builder diff --git a/content/habitat/builder_api.md b/content/habitat/builder_api.md new file mode 100644 index 0000000000..6a9d933898 --- /dev/null +++ b/content/habitat/builder_api.md @@ -0,0 +1,4 @@ ++++ +layout = "redirect" +redirect_url = "https://docs.chef.io/habitat/saas_builder/builder_api/" ++++ diff --git a/content/habitat/builder_origin_packages.md b/content/habitat/builder_origin_packages.md new file mode 100644 index 0000000000..affa6167ad --- /dev/null +++ b/content/habitat/builder_origin_packages.md @@ -0,0 +1,4 @@ ++++ +layout = "redirect" +redirect_url = "https://docs.chef.io/habitat/saas_builder/builder_origin_packages/" ++++ diff --git a/content/habitat/builder_origins.md b/content/habitat/builder_origins.md new file mode 100644 index 0000000000..47c80fccf3 --- /dev/null +++ b/content/habitat/builder_origins.md @@ -0,0 +1,4 @@ ++++ +layout = "redirect" +redirect_url = "https://docs.chef.io/habitat/saas_builder/builder_origins/" ++++ diff --git a/content/habitat/builder_overview.md b/content/habitat/builder_overview.md new file mode 100644 index 0000000000..c32b5d1821 --- /dev/null +++ b/content/habitat/builder_overview.md @@ -0,0 +1,4 @@ ++++ +layout = "redirect" +redirect_url = "https://docs.chef.io/habitat/saas_builder/" ++++ diff --git a/content/habitat/environment_variables.md b/content/habitat/environment_variables.md new file mode 100644 index 0000000000..a2de6fe6f5 --- /dev/null +++ b/content/habitat/environment_variables.md @@ -0,0 +1,4 @@ ++++ +layout = "redirect" +redirect_url = "https://docs.chef.io/habitat/latest/reference/environment_variables/" ++++ diff --git a/content/habitat/habitat_cli.md b/content/habitat/habitat_cli.md index 8bdaea2d9f..dc7c49a3db 100644 --- a/content/habitat/habitat_cli.md +++ b/content/habitat/habitat_cli.md @@ -1,3779 +1,4 @@ +++ -title = "Chef Habitat Command-Line Interface (CLI) Reference" -draft= false - -[menu] - [menu.habitat] - title = "Habitat CLI Reference" - identifier = "habitat/reference/Habitat CLI Reference" - parent = "habitat/reference" - weight = 10 +layout = "redirect" +redirect_url = "https://docs.chef.io/habitat/latest/reference/habitat_cli/" +++ - - - - - -The commands for the Chef Habitat CLI (`hab`) are listed below. - -| Applies to Version | Last Updated | -| ------- | ------------ | -| hab 1.6.1245/20250905140900 (linux) | 5 Sep 2025 | - -## hab - - - -**USAGE** - -``` -hab -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - -**ALIASES** - -``` -apply Alias for: 'config apply' -install Alias for: 'pkg install' -run Alias for: 'sup run' -setup Alias for: 'cli setup' -start Alias for: 'svc start' -stop Alias for: 'svc stop' -term Alias for: 'sup term' -``` - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab bldr](#hab-bldr) | Commands relating to Habitat Builder | -| [hab cli](#hab-cli) | Commands relating to Habitat runtime config | -| [hab config](#hab-config) | Commands relating to a Service's runtime config | -| [hab file](#hab-file) | Commands relating to Habitat files | -| [hab license](#hab-license) | Commands relating to Habitat license agreements | -| [hab origin](#hab-origin) | Commands relating to Habitat Builder origins | -| [hab pkg](#hab-pkg) | Commands relating to Habitat packages | -| [hab plan](#hab-plan) | Commands relating to plans and other app-specific configuration | -| [hab ring](#hab-ring) | Commands relating to Habitat rings | -| [hab studio](#hab-studio) | Commands relating to Habitat Studios | -| [hab sup](#hab-sup) | The Habitat Supervisor | -| [hab supportbundle](#hab-supportbundle) | Create a tarball of Habitat Supervisor data to send to support | -| [hab svc](#hab-svc) | Commands relating to Habitat services | -| [hab user](#hab-user) | Commands relating to Habitat users | ---- - -## hab bldr - -Commands relating to Habitat Builder - -**USAGE** - -``` -hab bldr -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab bldr channel](#hab-bldr-channel) | Commands relating to Habitat Builder channels | -| [hab bldr job](#hab-bldr-job) | REMOVED: Commands relating to Habitat Builder jobs | ---- - -### hab bldr channel - -Commands relating to Habitat Builder channels - -**USAGE** - -``` -hab bldr channel -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab bldr channel create](#hab-bldr-channel-create) | Creates a new channel | -| [hab bldr channel demote](#hab-bldr-channel-demote) | Atomically demotes selected packages in a target channel | -| [hab bldr channel destroy](#hab-bldr-channel-destroy) | Destroys a channel | -| [hab bldr channel list](#hab-bldr-channel-list) | Lists origin channels | -| [hab bldr channel promote](#hab-bldr-channel-promote) | Atomically promotes all packages in channel | ---- - -### hab bldr channel create - -Creates a new channel - -**USAGE** - -``` -hab bldr channel create [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) --o, --origin Sets the origin to which the channel will belong. Default is from 'HAB_ORIGIN' or cli.toml -``` - -**ARGS** - -``` - The channel name -``` - - - ---- - -### hab bldr channel demote - -Atomically demotes selected packages in a target channel - -**USAGE** - -``` -hab bldr channel demote [OPTIONS] --origin -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) --o, --origin The origin for the channels. Default is from 'HAB_ORIGIN' or cli.toml -``` - -**ARGS** - -``` - The channel from which all packages will be selected for demotion - The channel selected packages will be removed from -``` - - - ---- - -### hab bldr channel destroy - -Destroys a channel - -**USAGE** - -``` -hab bldr channel destroy [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) --o, --origin Sets the origin to which the channel belongs. Default is from 'HAB_ORIGIN' or cli.toml -``` - -**ARGS** - -``` - The channel name -``` - - - ---- - -### hab bldr channel list - -Lists origin channels - -**USAGE** - -``` -hab bldr channel list [FLAGS] [OPTIONS] [ORIGIN] -``` - -**FLAGS** - -``` --s, --sandbox Include sandbox channels for the origin --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) -``` - -**ARGS** - -``` - The origin for which channels will be listed. Default is from 'HAB_ORIGIN' or cli.toml -``` - - - ---- - -### hab bldr channel promote - -Atomically promotes all packages in channel - -**USAGE** - -``` -hab bldr channel promote [OPTIONS] --origin -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) --o, --origin The origin for the channels. Default is from 'HAB_ORIGIN' or cli.toml -``` - -**ARGS** - -``` - The channel from which all packages will be selected for promotion - The channel to which packages will be promoted -``` - - - ---- - -### hab bldr job - -REMOVED: Commands relating to Habitat Builder jobs - -**USAGE** - -``` -hab bldr job -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab bldr job cancel](#hab-bldr-job-cancel) | REMOVED: Cancel a build job group and any in-progress builds | -| [hab bldr job demote](#hab-bldr-job-demote) | REMOVED: Demote packages from a completed build job from a specified channel | -| [hab bldr job promote](#hab-bldr-job-promote) | REMOVED: Promote packages from a completed build job to a specified channel | -| [hab bldr job start](#hab-bldr-job-start) | REMOVED: Schedule a build job or group of jobs | -| [hab bldr job status](#hab-bldr-job-status) | REMOVED: Get the status of one or more job groups | ---- - -### hab bldr job cancel - -REMOVED: Cancel a build job group and any in-progress builds - -**USAGE** - -``` -hab bldr job cancel [FLAGS] [OPTIONS] -``` - -**FLAGS** - -``` --f, --force Don't prompt for confirmation --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) -``` - -**ARGS** - -``` - The job group id that was returned from "hab bldr job start" (ex: 771100000000000000) -``` - - - ---- - -### hab bldr job demote - -REMOVED: Demote packages from a completed build job from a specified channel - -**USAGE** - -``` -hab bldr job demote [FLAGS] [OPTIONS] -``` - -**FLAGS** - -``` --i, --interactive Allow editing the list of demotable packages --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) --o, --origin Limit the demotable packages to the specified origin -``` - -**ARGS** - -``` - The job group id that was returned from "hab bldr job start" (ex: 771100000000000000) - The name of the channel to demote from -``` - - - ---- - -### hab bldr job promote - -REMOVED: Promote packages from a completed build job to a specified channel - -**USAGE** - -``` -hab bldr job promote [FLAGS] [OPTIONS] -``` - -**FLAGS** - -``` --i, --interactive Allow editing the list of promotable packages --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) --o, --origin Limit the promotable packages to the specified origin -``` - -**ARGS** - -``` - The job group id that was returned from "hab bldr job start" (ex: 771100000000000000) - The target channel name -``` - - - ---- - -### hab bldr job start - -REMOVED: Schedule a build job or group of jobs - -**USAGE** - -``` -hab bldr job start [FLAGS] [OPTIONS] [PKG_TARGET] -``` - -**FLAGS** - -``` --g, --group Schedule jobs for this package and all of its reverse dependencies --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) -``` - -**ARGS** - -``` - A package identifier (ex: core/redis, core/busybox-static/1.42.2) - A package target (ex: x86_64-windows) (default: system appropriate target) [env: HAB_PACKAGE_TARGET=] -``` - - - ---- - -### hab bldr job status - -REMOVED: Get the status of one or more job groups - -**USAGE** - -``` -hab bldr job status [FLAGS] [OPTIONS] > -``` - -**FLAGS** - -``` --s, --showjobs Show the status of all build jobs for a retrieved job group --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) --l, --limit Limit how many job groups to retrieve, ordered by most recent (default: 10) --o, --origin Show the status of recent job groups created in this origin (default: 10 most recent) -``` - -**ARGS** - -``` - The job group id that was returned from "hab bldr job start" (ex: 771100000000000000) -``` - - - ---- - -## hab cli - -Commands relating to Habitat runtime config - -**USAGE** - -``` -hab cli -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab cli completers](#hab-cli-completers) | Creates command-line completers for your shell | -| [hab cli setup](#hab-cli-setup) | Sets up the CLI with reasonable defaults | ---- - -### hab cli completers - -Creates command-line completers for your shell - -**USAGE** - -``` -hab cli completers --shell -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --s, --shell The name of the shell you want to generate the command-completion [possible values: Bash, Fish, Zsh, PowerShell] -``` - - - - ---- - -### hab cli setup - -Sets up the CLI with reasonable defaults - -**USAGE** - -``` -hab cli setup [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` ---cache-key-path Cache for creating and searching for encryption keys [env: HAB_CACHE_KEY_PATH=] [default: /hab/cache/keys] -``` - - - - ---- - -## hab config - -Commands relating to a Service's runtime config - -**USAGE** - -``` -hab config -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab config apply](#hab-config-apply) | Sets a configuration to be shared by members of a Service Group | -| [hab config show](#hab-config-show) | Displays the default configuration options for a service | ---- - -### hab config apply - -Sets a configuration to be shared by members of a Service Group - -**USAGE** - -``` -hab config apply [OPTIONS] [FILE] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` ---cache-key-path Cache for creating and searching for encryption keys [env: HAB_CACHE_KEY_PATH=] [default: /hab/cache/keys] --r, --remote-sup Address to a remote Supervisor's Control Gateway [default: 127.0.0.1:9632] --u, --user Name of a user key to use for encryption -``` - -**ARGS** - -``` - Target service group service.group[@organization] (ex: redis.default or foo.default@bazcorp) - A version number (positive integer) for this configuration (ex: 42) - Path to local file on disk (ex: /tmp/config.toml, default: ) -``` - - - ---- - -### hab config show - -Displays the default configuration options for a service - -**USAGE** - -``` -hab config show [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --r, --remote-sup Address to a remote Supervisor's Control Gateway [default: 127.0.0.1:9632] -``` - -**ARGS** - -``` - A package identifier (ex: core/redis, core/busybox-static/1.42.2) -``` - - - ---- - -## hab file - -Commands relating to Habitat files - -**USAGE** - -``` -hab file -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab file upload](#hab-file-upload) | Uploads a file to be shared between members of a Service Group | ---- - -### hab file upload - -Uploads a file to be shared between members of a Service Group - -**USAGE** - -``` -hab file upload [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` ---cache-key-path Cache for creating and searching for encryption keys [env: HAB_CACHE_KEY_PATH=] [default: /hab/cache/keys] --r, --remote-sup Address to a remote Supervisor's Control Gateway [default: 127.0.0.1:9632] --u, --user Name of the user key -``` - -**ARGS** - -``` - Target service group service.group[@organization] (ex: redis.default or foo.default@bazcorp) - A version number (positive integer) for this configuration (ex: 42) - Path to local file on disk -``` - - - ---- - -## hab license - -Commands relating to Habitat license agreements - -**USAGE** - -``` -hab license -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab license accept](#hab-license-accept) | Accept the Chef Binary Distribution Agreement without prompting | ---- - -### hab license accept - -Accept the Chef Binary Distribution Agreement without prompting - -**USAGE** - -``` -hab license accept -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - - ---- - -## hab origin - -Commands relating to Habitat Builder origins - -**USAGE** - -``` -hab origin -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab origin create](#hab-origin-create) | Creates a new Builder origin | -| [hab origin delete](#hab-origin-delete) | Removes an unused/empty origin | -| [hab origin depart](#hab-origin-depart) | Departs membership from selected origin | -| [hab origin info](#hab-origin-info) | Displays general information about an origin | -| [hab origin invitations](#hab-origin-invitations) | Manage origin member invitations | -| [hab origin key](#hab-origin-key) | Commands relating to Habitat origin key maintenance | -| [hab origin rbac](#hab-origin-rbac) | Role Based Access Control for origin members | -| [hab origin secret](#hab-origin-secret) | Commands related to secret management | -| [hab origin transfer](#hab-origin-transfer) | Transfers ownership of an origin to another member of that origin | ---- - -### hab origin create - -Creates a new Builder origin - -**USAGE** - -``` -hab origin create [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) -``` - -**ARGS** - -``` - The origin to be created -``` - - - ---- - -### hab origin delete - -Removes an unused/empty origin - -**USAGE** - -``` -hab origin delete [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) -``` - -**ARGS** - -``` - The origin name -``` - - - ---- - -### hab origin depart - -Departs membership from selected origin - -**USAGE** - -``` -hab origin depart [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) -``` - -**ARGS** - -``` - The origin name -``` - - - ---- - -### hab origin info - -Displays general information about an origin - -**USAGE** - -``` -hab origin info [FLAGS] [OPTIONS] -``` - -**FLAGS** - -``` --j, --json Output will be rendered in json --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) -``` - -**ARGS** - -``` - The origin name to be queried -``` - - - ---- - -### hab origin invitations - -Manage origin member invitations - -**USAGE** - -``` -hab origin invitations -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab origin invitations accept](#hab-origin-invitations-accept) | Accept an origin member invitation | -| [hab origin invitations ignore](#hab-origin-invitations-ignore) | Ignore an origin member invitation | -| [hab origin invitations list](#hab-origin-invitations-list) | List origin invitations sent to your account | -| [hab origin invitations pending](#hab-origin-invitations-pending) | List pending invitations for a particular origin. Requires that you are the origin owner | -| [hab origin invitations rescind](#hab-origin-invitations-rescind) | Rescind an existing origin member invitation | -| [hab origin invitations send](#hab-origin-invitations-send) | Send an origin member invitation | ---- - -### hab origin invitations accept - -Accept an origin member invitation - -**USAGE** - -``` -hab origin invitations accept [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) -``` - -**ARGS** - -``` - The origin name the invitation applies to - The id of the invitation to accept -``` - - - ---- - -### hab origin invitations ignore - -Ignore an origin member invitation - -**USAGE** - -``` -hab origin invitations ignore [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) -``` - -**ARGS** - -``` - The origin name the invitation applies to - The id of the invitation to ignore -``` - - - ---- - -### hab origin invitations list - -List origin invitations sent to your account - -**USAGE** - -``` -hab origin invitations list [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) -``` - - - - ---- - -### hab origin invitations pending - -List pending invitations for a particular origin. Requires that you are the origin owner - -**USAGE** - -``` -hab origin invitations pending [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) -``` - -**ARGS** - -``` - The name of the origin you wish to list invitations for -``` - - - ---- - -### hab origin invitations rescind - -Rescind an existing origin member invitation - -**USAGE** - -``` -hab origin invitations rescind [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) -``` - -**ARGS** - -``` - The origin name the invitation applies to - The id of the invitation to rescind -``` - - - ---- - -### hab origin invitations send - -Send an origin member invitation - -**USAGE** - -``` -hab origin invitations send [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) -``` - -**ARGS** - -``` - The origin name the invitation applies to - The account name to invite into the origin -``` - - - ---- - -### hab origin key - -Commands relating to Habitat origin key maintenance - -**USAGE** - -``` -hab origin key -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab origin key download](#hab-origin-key-download) | Download origin key(s) | -| [hab origin key export](#hab-origin-key-export) | Outputs the latest origin key contents to stdout | -| [hab origin key generate](#hab-origin-key-generate) | Generates a Habitat origin key pair | -| [hab origin key import](#hab-origin-key-import) | Reads a stdin stream containing a public or private origin key contents and writes the key to disk | -| [hab origin key upload](#hab-origin-key-upload) | Upload origin keys to Builder | ---- - -### hab origin key download - -Download origin key(s) - -**USAGE** - -``` -hab origin key download [FLAGS] [OPTIONS] [REVISION] -``` - -**FLAGS** - -``` --e, --encryption Download public encryption key instead of origin public key --s, --secret Download origin private key instead of origin public key --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder (required for downloading origin private keys) --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) - --cache-key-path Cache for creating and searching for encryption keys [env: HAB_CACHE_KEY_PATH=] [default: /hab/cache/keys] -``` - -**ARGS** - -``` - The origin name - The origin key revision -``` - - - ---- - -### hab origin key export - -Outputs the latest origin key contents to stdout - -**USAGE** - -``` -hab origin key export [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` ---cache-key-path Cache for creating and searching for encryption keys [env: HAB_CACHE_KEY_PATH=] [default: /hab/cache/keys] --t, --type Export either the 'public' or 'secret' key. The 'secret' key is the origin private key -``` - -**ARGS** - -``` - The origin name -``` - - - ---- - -### hab origin key generate - -Generates a Habitat origin key pair - -**USAGE** - -``` -hab origin key generate [OPTIONS] [ORIGIN] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` ---cache-key-path Cache for creating and searching for encryption keys [env: HAB_CACHE_KEY_PATH=] [default: /hab/cache/keys] -``` - -**ARGS** - -``` - The origin name -``` - - - ---- - -### hab origin key import - -Reads a stdin stream containing a public or private origin key contents and writes the key to disk - -**USAGE** - -``` -hab origin key import [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` ---cache-key-path Cache for creating and searching for encryption keys [env: HAB_CACHE_KEY_PATH=] [default: /hab/cache/keys] -``` - - - - ---- - -### hab origin key upload - -Upload origin keys to Builder - -**USAGE** - -``` -hab origin key upload [FLAGS] [OPTIONS] > -``` - -**FLAGS** - -``` --s, --secret Upload origin private key in addition to the public key --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) - --cache-key-path Cache for creating and searching for encryption keys [env: HAB_CACHE_KEY_PATH=] [default: /hab/cache/keys] - --pubfile Path to a local public origin key file on disk - --secfile Path to a local origin private key file on disk -``` - -**ARGS** - -``` - The origin name -``` - - - ---- - -### hab origin rbac - -Role Based Access Control for origin members - -**USAGE** - -``` -hab origin rbac -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab origin rbac set](#hab-origin-rbac-set) | Change an origin member's role | -| [hab origin rbac show](#hab-origin-rbac-show) | Display an origin member's current role | ---- - -### hab origin rbac set - -Change an origin member's role - -**USAGE** - -``` -hab origin rbac set [FLAGS] [OPTIONS] --origin -``` - -**FLAGS** - -``` --n, --no-prompt Do not prompt for confirmation --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) --o, --origin The Builder origin name to target -``` - -**ARGS** - -``` - The account name whose role will be changed - The role name to enforce for the member account [possible values: readonly_member, member, maintainer, administrator, owner] -``` - - - ---- - -### hab origin rbac show - -Display an origin member's current role - -**USAGE** - -``` -hab origin rbac show [FLAGS] [OPTIONS] --origin -``` - -**FLAGS** - -``` --j, --json Output will be rendered in json --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) --o, --origin The Builder origin name to target -``` - -**ARGS** - -``` - The account name of the role to display -``` - - - ---- - -### hab origin secret - -Commands related to secret management - -**USAGE** - -``` -hab origin secret -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab origin secret delete](#hab-origin-secret-delete) | Delete a secret for your origin | -| [hab origin secret list](#hab-origin-secret-list) | List all secrets for your origin | -| [hab origin secret upload](#hab-origin-secret-upload) | Create and upload a secret for your origin | ---- - -### hab origin secret delete - -Delete a secret for your origin - -**USAGE** - -``` -hab origin secret delete [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) --o, --origin The origin for which the secret will be deleted. Default is from 'HAB_ORIGIN' or cli.toml -``` - -**ARGS** - -``` - The name of the variable key to be injected into the studio -``` - - - ---- - -### hab origin secret list - -List all secrets for your origin - -**USAGE** - -``` -hab origin secret list [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) --o, --origin The origin for which secrets will be listed. Default is from 'HAB_ORIGIN' or cli.toml -``` - - - - ---- - -### hab origin secret upload - -Create and upload a secret for your origin - -**USAGE** - -``` -hab origin secret upload [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) - --cache-key-path Cache for creating and searching for encryption keys [env: HAB_CACHE_KEY_PATH=] [default: /hab/cache/keys] --o, --origin The origin for which the secret will be uploaded. Default is from HAB_ORIGIN' or cli.toml -``` - -**ARGS** - -``` - The name of the variable key to be injected into the studio. Ex: KEY="some_value" - The contents of the variable to be injected into the studio -``` - - - ---- - -### hab origin transfer - -Transfers ownership of an origin to another member of that origin - -**USAGE** - -``` -hab origin transfer [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) -``` - -**ARGS** - -``` - The origin name - The account name of the new origin owner -``` - - - ---- - -## hab pkg - -Commands relating to Habitat packages - -**USAGE** - -``` -hab pkg -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab pkg binds](#hab-pkg-binds) | Displays the binds for a service | -| [hab pkg binlink](#hab-pkg-binlink) | Creates a binlink for a package binary in a common 'PATH' location | -| [hab pkg build](#hab-pkg-build) | Builds a Plan using a Studio | -| [hab pkg bulkupload](#hab-pkg-bulkupload) | Bulk Uploads Habitat Artifacts to a Depot from a local directory | -| [hab pkg channels](#hab-pkg-channels) | Find out what channels a package belongs to | -| [hab pkg config](#hab-pkg-config) | Displays the default configuration options for a service | -| [hab pkg delete](#hab-pkg-delete) | Removes a package from Builder | -| [hab pkg demote](#hab-pkg-demote) | Demote a package from a specified channel | -| [hab pkg dependencies](#hab-pkg-dependencies) | Returns the Habitat Artifact dependencies. By default it will return the direct dependencies of the package | -| [hab pkg download](#hab-pkg-download) | Download Habitat artifacts (including dependencies and keys) from Builder | -| [hab pkg env](#hab-pkg-env) | Prints the runtime environment of a specific installed package | -| [hab pkg exec](#hab-pkg-exec) | Executes a command using the 'PATH' context of an installed package | -| [hab pkg export](#hab-pkg-export) | Exports the package to the specified format | -| [hab pkg hash](#hab-pkg-hash) | Generates a blake2b hashsum from a target at any given filepath | -| [hab pkg info](#hab-pkg-info) | Returns the Habitat Artifact information | -| [hab pkg install](#hab-pkg-install) | Installs a Habitat package from Builder or locally from a Habitat Artifact | -| [hab pkg list](#hab-pkg-list) | List all versions of installed packages | -| [hab pkg path](#hab-pkg-path) | Prints the path to a specific installed release of a package | -| [hab pkg promote](#hab-pkg-promote) | Promote a package to a specified channel | -| [hab pkg provides](#hab-pkg-provides) | Search installed Habitat packages for a given file | -| [hab pkg search](#hab-pkg-search) | Search for a package in Builder | -| [hab pkg sign](#hab-pkg-sign) | Signs an archive with an origin key, generating a Habitat Artifact | -| [hab pkg uninstall](#hab-pkg-uninstall) | Safely uninstall a package and dependencies from the local filesystem | -| [hab pkg upload](#hab-pkg-upload) | Uploads a local Habitat Artifact to Builder | -| [hab pkg verify](#hab-pkg-verify) | Verifies a Habitat Artifact with an origin key | ---- - -### hab pkg binds - -Displays the binds for a service - -**USAGE** - -``` -hab pkg binds -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - -**ARGS** - -``` - A package identifier (ex: core/redis, core/busybox-static/1.42.2) -``` - - - ---- - -### hab pkg binlink - -Creates a binlink for a package binary in a common 'PATH' location - -**USAGE** - -``` -hab pkg binlink [FLAGS] [OPTIONS] [BINARY] -``` - -**FLAGS** - -``` --f, --force Overwrite existing binlinks --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --d, --dest Sets the destination directory [env: HAB_BINLINK_DIR=] [default: /bin] -``` - -**ARGS** - -``` - A package identifier (ex: core/redis, core/busybox-static/1.42.2) - The command to binlink (ex: bash) -``` - - - ---- - -### hab pkg build - -Builds a Plan using a Studio - -**USAGE** - -``` -hab pkg build [FLAGS] [OPTIONS] -``` - -**FLAGS** - -``` --D, --docker Uses a Dockerized Studio for the build --N, --native-package Build a native package on the host system without a studio --R, --reuse Reuses a previous Studio for the build (default: clean up before building) --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` ---cache-key-path Cache for creating and searching for encryption keys [env: HAB_CACHE_KEY_PATH=] [default: /hab/cache/keys] --k, --keys Installs secret origin keys (ex: "unicorn", "acme,other,acme-ops") --r, --root Sets the Studio root (default: /hab/studios/) --f, --refresh-channel Channel used to retrieve plan dependencies for Chef supported origins env: HAB_REFRESH_CHANNEL=stable] [default: stable] --s, --src Sets the source path (default: $PWD) -``` - -**ARGS** - -``` - A directory containing a plan file or a habitat/ directory which contains the plan file -``` - - - ---- - -### hab pkg bulkupload - -Bulk Uploads Habitat Artifacts to a Depot from a local directory - -**USAGE** - -``` -hab pkg bulkupload [FLAGS] [OPTIONS] -``` - -**FLAGS** - -``` ---auto-build Enable auto-build for all packages in this upload. Only applicable to SaaS Builder - --auto-create-origins Skip the confirmation prompt and automatically create origins that do not exist in the target Builder - --force Skip checking availability of package and force uploads, potentially overwriting a stored copy of a package --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) --c, --channel Optional additional release channel to upload package to. Packages are always uploaded to unstable, regardless of the value of this option -``` - -**ARGS** - -``` - Directory Path from which artifacts will be uploaded -``` - - - ---- - -### hab pkg channels - -Find out what channels a package belongs to - -**USAGE** - -``` -hab pkg channels [OPTIONS] [PKG_TARGET] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) -``` - -**ARGS** - -``` - A fully qualified package identifier (ex: core/busybox-static/1.42.2/20170513215502) - A package target (ex: x86_64-windows) (default: system appropriate target) [env: HAB_PACKAGE_TARGET=] -``` - - - ---- - -### hab pkg config - -Displays the default configuration options for a service - -**USAGE** - -``` -hab pkg config -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - -**ARGS** - -``` - A package identifier (ex: core/redis, core/busybox-static/1.42.2) -``` - - - ---- - -### hab pkg delete - -Removes a package from Builder - -**USAGE** - -``` -hab pkg delete [OPTIONS] [PKG_TARGET] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) -``` - -**ARGS** - -``` - A fully qualified package identifier (ex: core/busybox-static/1.42.2/20170513215502) - A package target (ex: x86_64-windows) (default: system appropriate target) [env: HAB_PACKAGE_TARGET=] -``` - - - ---- - -### hab pkg demote - -Demote a package from a specified channel - -**USAGE** - -``` -hab pkg demote [OPTIONS] [PKG_TARGET] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) -``` - -**ARGS** - -``` - A fully qualified package identifier (ex: core/busybox-static/1.42.2/20170513215502) - Demote from the specified release channel - A package target (ex: x86_64-windows) (default: system appropriate target) [env: HAB_PACKAGE_TARGET=] -``` - - - ---- - -### hab pkg dependencies - -Returns the Habitat Artifact dependencies. By default it will return the direct dependencies of the package - -**USAGE** - -``` -hab pkg dependencies [FLAGS] -``` - -**FLAGS** - -``` --r, --reverse Show packages which are dependant on this one --t, --transitive Show transitive dependencies --h, --help Prints help information --V, --version Prints version information -``` - - -**ARGS** - -``` - A package identifier (ex: core/redis, core/busybox-static/1.42.2) -``` - - - ---- - -### hab pkg download - -Download Habitat artifacts (including dependencies and keys) from Builder - -**USAGE** - -``` -hab pkg download [FLAGS] [OPTIONS] [--] [PKG_IDENT]... -``` - -**FLAGS** - -``` ---ignore-missing-seeds Ignore packages specified that are not present on the target Builder - --verify Verify package integrity after download (Warning: this can be slow) --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) --c, --channel Download from the specified release channel. Overridden if channel is specified in toml file [env: HAB_BLDR_CHANNEL=] [default: stable] - --download-directory The path to store downloaded artifacts - --file ... File with newline separated package identifiers, or TOML file (ending with .toml extension) - --t, --target Target architecture to fetch. E.g. x86_64-linux. Overridden if architecture is specified in toml file -``` - -**ARGS** - -``` -... One or more Habitat package identifiers (ex: acme/redis) -``` - - - ---- - -### hab pkg env - -Prints the runtime environment of a specific installed package - -**USAGE** - -``` -hab pkg env -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - -**ARGS** - -``` - A package identifier (ex: core/redis, core/busybox-static/1.42.2) -``` - - - ---- - -### hab pkg exec - -Executes a command using the 'PATH' context of an installed package - -**USAGE** - -``` -hab pkg exec [ARGS]... -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - -**ARGS** - -``` - A package identifier (ex: core/redis, core/busybox-static/1.42.2) - The command to execute (ex: ls) -... Arguments to the command -``` - - - ---- - -### hab pkg export - -Exports the package to the specified format - -**USAGE** - -``` -hab pkg export -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab pkg export cf](#hab-pkg-export-cf) | Cloud Foundry exporter | -| [hab pkg export container](#hab-pkg-export-container) | Container exporter | -| [hab pkg export mesos](#hab-pkg-export-mesos) | Mesos exporter | -| [hab pkg export tar](#hab-pkg-export-tar) | Tar exporter | ---- - -### hab pkg hash - -Generates a blake2b hashsum from a target at any given filepath - -**USAGE** - -``` -hab pkg hash [SOURCE] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - -**ARGS** - -``` - A filepath of the target -``` - - - ---- - -### hab pkg info - -Returns the Habitat Artifact information - -**USAGE** - -``` -hab pkg info [FLAGS] -``` - -**FLAGS** - -``` --j, --json Output will be rendered in json. (Includes extended metadata) --h, --help Prints help information --V, --version Prints version information -``` - - -**ARGS** - -``` - A path to a Habitat Artifact (ex: /home/acme-redis-3.0.7-21120102031201-x86_64-linux.hart) -``` - - - ---- - -### hab pkg install - -Installs a Habitat package from Builder or locally from a Habitat Artifact - -**USAGE** - -``` -hab pkg install [FLAGS] [OPTIONS] ... -``` - -**FLAGS** - -``` --b, --binlink Binlink all binaries from installed package(s) into BINLINK_DIR --f, --force Overwrite existing binlinks - --ignore-install-hook Do not run any install hooks - --ignore-local Do not use locally-installed packages when a corresponding package cannot be installed from Builder --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] - --binlink-dir Binlink all binaries from installed package(s) into BINLINK_DIR [env: HAB_BINLINK_DIR=] [default: /bin] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) --c, --channel Install from the specified release channel [env: HAB_BLDR_CHANNEL=] [default: stable] -``` - -**ARGS** - -``` -... One or more Habitat package identifiers (ex: acme/redis) and/or filepaths to a Habitat Artifact (ex: /home/acme-redis-3.0.7-21120102031201-x86_64-linux.hart) -``` - - - ---- - -### hab pkg list - -List all versions of installed packages - -**USAGE** - -``` -hab pkg list [OPTIONS] <--all|--origin |PKG_IDENT> -``` - -**FLAGS** - -``` --a, --all List all installed packages --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --o, --origin An origin to list -``` - -**ARGS** - -``` - A package identifier (ex: core/redis, core/busybox-static/1.42.2) -``` - - - ---- - -### hab pkg path - -Prints the path to a specific installed release of a package - -**USAGE** - -``` -hab pkg path -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - -**ARGS** - -``` - A package identifier (ex: core/redis, core/busybox-static/1.42.2) -``` - - - ---- - -### hab pkg promote - -Promote a package to a specified channel - -**USAGE** - -``` -hab pkg promote [OPTIONS] [PKG_TARGET] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) -``` - -**ARGS** - -``` - A fully qualified package identifier (ex: core/busybox-static/1.42.2/20170513215502) - Promote to the specified release channel - A package target (ex: x86_64-windows) (default: system appropriate target) [env: HAB_PACKAGE_TARGET=] -``` - - - ---- - -### hab pkg provides - -Search installed Habitat packages for a given file - -**USAGE** - -``` -hab pkg provides [FLAGS] -``` - -**FLAGS** - -``` --p Show full path to file --r Show fully qualified package names (ex: core/busybox-static/1.24.2/20160708162350) --h, --help Prints help information --V, --version Prints version information -``` - - -**ARGS** - -``` - File name to find -``` - - - ---- - -### hab pkg search - -Search for a package in Builder - -**USAGE** - -``` -hab pkg search [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) --l, --limit Limit how many packages to retrieve [default: 50] -``` - -**ARGS** - -``` - Search term -``` - - - ---- - -### hab pkg sign - -Signs an archive with an origin key, generating a Habitat Artifact - -**USAGE** - -``` -hab pkg sign [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` ---cache-key-path Cache for creating and searching for encryption keys [env: HAB_CACHE_KEY_PATH=] [default: /hab/cache/keys] - --origin Origin key used to create signature -``` - -**ARGS** - -``` - A path to a source archive file (ex: /home/acme-redis-3.0.7-21120102031201.tar.xz) - The destination path to the signed Habitat Artifact (ex: /home/acme-redis-3.0.7-21120102031201- x86_64-linux.hart) -``` - - - ---- - -### hab pkg uninstall - -Safely uninstall a package and dependencies from the local filesystem - -**USAGE** - -``` -hab pkg uninstall [FLAGS] [OPTIONS] -``` - -**FLAGS** - -``` --d, --dryrun Just show what would be uninstalled, don't actually do it - --ignore-uninstall-hook Do not run any uninstall hooks - --no-deps Don't uninstall dependencies --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` ---exclude ... Identifier of one or more packages that should not be uninstalled. (ex: core/redis, core/busybox-static/1.42.2/21120102031201) - --keep-latest Only keep this number of latest packages uninstalling all others -``` - -**ARGS** - -``` - A package identifier (ex: core/redis, core/busybox-static/1.42.2) -``` - - - ---- - -### hab pkg upload - -Uploads a local Habitat Artifact to Builder - -**USAGE** - -``` -hab pkg upload [FLAGS] [OPTIONS] ... -``` - -**FLAGS** - -``` ---force Skips checking availability of package and force uploads, potentially overwriting a stored copy of a package. (default: false) - --no-build Disable auto-build for all packages in this upload --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --z, --auth Authentication token for Builder [env: HAB_AUTH_TOKEN=] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) - --cache-key-path Cache for creating and searching for encryption keys [env: HAB_CACHE_KEY_PATH=] [default: /hab/cache/keys] --c, --channel Optional additional release channel to upload package to. Packages are always uploaded to unstable, regardless of the value of this option -``` - -**ARGS** - -``` -... One or more filepaths to a Habitat Artifact (ex: /home/acme-redis-3.0.7-21120102031201-x86_64- linux.hart) -``` - - - ---- - -### hab pkg verify - -Verifies a Habitat Artifact with an origin key - -**USAGE** - -``` -hab pkg verify [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` ---cache-key-path Cache for creating and searching for encryption keys [env: HAB_CACHE_KEY_PATH=] [default: /hab/cache/keys] -``` - -**ARGS** - -``` - A path to a Habitat Artifact (ex: /home/acme-redis-3.0.7-21120102031201-x86_64-linux.hart) -``` - - - ---- - -## hab plan - -Commands relating to plans and other app-specific configuration - -**USAGE** - -``` -hab plan -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab plan init](#hab-plan-init) | Generates common package specific configuration files. Executing without argument will create a habitat directory in your current folder for the plan. If PKG_NAME is specified it will create a folder with that name. Environment variables (those starting with 'pkg_') that are set will be used in the generated plan | -| [hab plan render](#hab-plan-render) | Renders plan config files | ---- - -### hab plan init - -Generates common package specific configuration files. Executing without argument will create a habitat directory in - -**USAGE** - -``` -hab plan init [FLAGS] [OPTIONS] [PKG_NAME] -``` - -**FLAGS** - -``` --m, --min Create a minimal plan file --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --o, --origin Origin for the new app --s, --scaffolding Specify explicit Scaffolding for your app (ex: node, ruby) -``` - -**ARGS** - -``` - Name for the new app -``` - - - ---- - -### hab plan render - -Renders plan config files - -**USAGE** - -``` -hab plan render [FLAGS] [OPTIONS] -``` - -**FLAGS** - -``` --n, --no-render Don't write anything to disk, ignores --render-dir --p, --print Prints config to STDOUT --q, --quiet Don't print any helper messages. When used with --print will only print config file --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --d, --default-toml Path to default.toml [default: ./default.toml] --m, --mock-data Path to json file with mock data for template, defaults to none --r, --render-dir Path to render templates [default: ./results] --u, --user-toml Path to user.toml, defaults to none -``` - -**ARGS** - -``` - Path to config to render -``` - - - ---- - -## hab ring - -Commands relating to Habitat rings - -**USAGE** - -``` -hab ring -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab ring key](#hab-ring-key) | Commands relating to Habitat ring keys | ---- - -### hab ring key - -Commands relating to Habitat ring keys - -**USAGE** - -``` -hab ring key -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab ring key export](#hab-ring-key-export) | Outputs the latest ring key contents to stdout | -| [hab ring key generate](#hab-ring-key-generate) | Generates a Habitat ring key | -| [hab ring key import](#hab-ring-key-import) | Reads a stdin stream containing ring key contents and writes the key to disk | ---- - -### hab ring key export - -Outputs the latest ring key contents to stdout - -**USAGE** - -``` -hab ring key export [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` ---cache-key-path Cache for creating and searching for encryption keys [env: HAB_CACHE_KEY_PATH=] [default: /hab/cache/keys] -``` - -**ARGS** - -``` - Ring key name -``` - - - ---- - -### hab ring key generate - -Generates a Habitat ring key - -**USAGE** - -``` -hab ring key generate [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` ---cache-key-path Cache for creating and searching for encryption keys [env: HAB_CACHE_KEY_PATH=] [default: /hab/cache/keys] -``` - -**ARGS** - -``` - Ring key name -``` - - - ---- - -### hab ring key import - -Reads a stdin stream containing ring key contents and writes the key to disk - -**USAGE** - -``` -hab ring key import [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` ---cache-key-path Cache for creating and searching for encryption keys [env: HAB_CACHE_KEY_PATH=] [default: /hab/cache/keys] -``` - - - - ---- - -## hab studio - - - -**USAGE** - -``` -hab studio [FLAGS] [OPTIONS] [ARG ..] -``` - - - - - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab studio build](#hab-studio-build) | Build using a Studio | -| [hab studio enter](#hab-studio-enter) | Interactively enter a Studio | -| [hab studio new](#hab-studio-new) | Creates a new Studio | -| [hab studio rm](#hab-studio-rm) | Destroys a Studio | -| [hab studio run](#hab-studio-run) | Run a command in a Studio | -| [hab studio version](#hab-studio-version) | Prints version information | ---- - -### hab studio build - - - -**USAGE** - -``` -hab studio [COMMON_FLAGS] [COMMON_OPTIONS] build [FLAGS] [PLAN_DIR] -``` - -**FLAGS** - -``` --R Reuse a previous Studio state (default: clean up before building) -``` - - - - - ---- - -### hab studio enter - - - -**USAGE** - -``` -hab studio [COMMON_FLAGS] [COMMON_OPTIONS] enter -``` - - - - - - ---- - -### hab studio new - - - -**USAGE** - -``` -hab studio [COMMON_FLAGS] [COMMON_OPTIONS] new -``` - - - - - - ---- - -### hab studio rm - - - -**USAGE** - -``` -hab studio [COMMON_FLAGS] [COMMON_OPTIONS] rm -``` - - - - - - ---- - -### hab studio run - - - -**USAGE** - -``` -hab studio [COMMON_FLAGS] [COMMON_OPTIONS] run [CMD] [ARG ..] -``` - - - - - - ---- - -### hab studio version - - - - - - - - - ---- - -## hab sup - - - -**USAGE** - -``` -hab sup -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab sup bash](#hab-sup-bash) | Start an interactive Bash-like shell | -| [hab sup depart](#hab-sup-depart) | Depart a Supervisor from the gossip ring; kicking and banning the target from joining again with the same member-id | -| [hab sup restart](#hab-sup-restart) | Restart a Supervisor without restarting its services | -| [hab sup run](#hab-sup-run) | Run the Habitat Supervisor | -| [hab sup secret](#hab-sup-secret) | Commands relating to a Habitat Supervisor's Control Gateway secret | -| [hab sup sh](#hab-sup-sh) | Start an interactive Bourne-like shell | -| [hab sup status](#hab-sup-status) | Query the status of Habitat services | -| [hab sup term](#hab-sup-term) | Gracefully terminate the Habitat Supervisor and all of its running services | ---- - -### hab sup bash - -Start an interactive Bash-like shell - -**USAGE** - -``` -hab sup bash -``` - -**FLAGS** - -``` --h, --help Prints help information -``` - - - - - ---- - -### hab sup depart - -Depart a Supervisor from the gossip ring; kicking and banning the target from joining again with the same member-id - -**USAGE** - -``` -hab sup depart [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information -``` - -**OPTIONS** - -``` --r, --remote-sup Address to a remote Supervisor's Control Gateway [default: 127.0.0.1:9632] -``` - -**ARGS** - -``` - The member-id of the Supervisor to depart -``` - - - ---- - -### hab sup restart - -Restart a Supervisor without restarting its services - -**USAGE** - -``` -hab sup restart [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information -``` - -**OPTIONS** - -``` --r, --remote-sup Address to a remote Supervisor's Control Gateway [default: 127.0.0.1:9632] -``` - - - - ---- - -### hab sup run - -Run the Habitat Supervisor - -**USAGE** - -``` -hab sup run [FLAGS] [OPTIONS] [--] [PKG_IDENT_OR_ARTIFACT] -``` - -**FLAGS** - -``` --A, --auto-update Enable automatic updates for the Supervisor itself - --generate-config Generate a TOML config --D, --http-disable Disable the HTTP Gateway completely - --json-logging Use structured JSON logging for the Supervisor - --local-gossip-mode Start the supervisor in local mode - --no-color Turn ANSI color off --I, --permanent-peer Make this Supervisor a permanent peer --v Verbose output showing file and line/column numbers --h, --help Prints help information -``` - -**OPTIONS** - -``` ---auto-update-period The period of time in seconds between Supervisor update checks [default: 60] - - --bind ... One or more service groups to bind to a configuration - - --binding-mode Governs how the presence or absence of binds affects service startup [default: strict] [possible values: strict, relaxed] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) - --cache-key-path Cache for creating and searching for encryption keys [env: HAB_CACHE_KEY_PATH=] [default: /hab/cache/keys] - - --ca-certs The CA certificate for HTTP Gateway TLS encryption - - --certs The server certificates for HTTP Gateway TLS encryption - - --channel Receive updates from the specified release channel [default: stable] - - --config-files ... Paths to config files to read - --config-from Use the package config from this path rather than the package itself - - --ctl-client-ca-certificate Enable client authentication for the control gateway and set the certificate authority to use when authenticating the client [default: /hab/cache/keys/ctl] - --ctl-server-certificate The control gateway server's TLS certificate [default: /hab/cache/keys/ctl] - - --ctl-server-key Enable TLS for the control gateway and set the server's private key [default: /hab/cache/keys/ctl] - - --event-meta ... An arbitrary key-value pair to add to each event generated by this Supervisor - - --event-stream-application The name of the application for event stream purposes - - --event-stream-connect-timeout Event stream connection timeout before exiting the Supervisor [env: HAB_EVENT_STREAM_CONNECT_TIMEOUT=] default: 0] - --event-stream-environment The name of the environment for event stream purposes - - --event-stream-server-certificate The path to Chef Automate's event stream certificate used to establish a TLS connection - - --event-stream-site The name of the site where this Supervisor is running for event stream purposes - - --event-stream-token The authentication token for connecting the event stream to Chef Automate [env: HAB_AUTOMATE_AUTH_TOKEN=] - - --event-stream-url The event stream connection url used to send events to Chef Automate - - --group The service group with shared config and topology [default: default] - --i, --health-check-interval The interval in seconds on which to run health checks [default: 30] - - --keep-latest-packages Automatically cleanup old packages [env: HAB_KEEP_LATEST_PACKAGES=] - - --key The private key for HTTP Gateway TLS encryption - - --listen-ctl The listen address for the Control Gateway [env: HAB_LISTEN_CTL=] [default: 127.0.0.1:9632] - - --listen-gossip The listen address for the Gossip Gateway [env: HAB_LISTEN_GOSSIP=] [default: 0.0.0.0:9638] - - --listen-http The listen address for the HTTP Gateway [env: HAB_LISTEN_HTTP=] [default: 0.0.0.0:9631] - - --org The organization the Supervisor and its services are part of - - --peer ... The listen address of one or more initial peers (IP[:PORT]) - - --peer-watch-file Watch this file for connecting to the ring - --r, --ring The name of the ring used by the Supervisor when running with wire encryption [env: HAB_RING=] - - --service-max-backoff-period The maximum period of time in seconds to wait before attempting to restart a service that failed to start up default: 0] - --service-min-backoff-period The minimum period of time in seconds to wait before attempting to restart a service that failed to start up default: 0] - --service-restart-cooldown-period The period of time in seconds to wait before assuming that a service started up successfully after a restart default: 300] - --service-update-period The period of time in seconds between service update checks [default: 60] - - --shutdown-timeout The delay in seconds after sending the shutdown signal to wait before killing the service process - --s, --strategy The update strategy [default: none] [possible values: none, at-once, rolling] - - --sys-ip-address The IPv4 address to use as the sys.ip template variable - --t, --topology Service topology [possible values: standalone, leader] - - --update-condition The condition dictating when this service should update [default: latest] [possible values: latest, track- channel] -``` - -**ARGS** - -``` - Load a Habitat package as part of the Supervisor startup -``` - - - ---- - -### hab sup secret - -Commands relating to a Habitat Supervisor's Control Gateway secret - -**USAGE** - -``` -hab sup secret -``` - -**FLAGS** - -``` --h, --help Prints help information -``` - - - - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab sup secret generate](#hab-sup-secret-generate) | Generate a secret key to use as a Supervisor's Control Gateway secret | -| [hab sup secret generate-tls](#hab-sup-secret-generate-tls) | Generate a private key and certificate for the Supervisor's Control Gateway TLS connection | ---- - -### hab sup secret generate - -Generate a secret key to use as a Supervisor's Control Gateway secret - -**USAGE** - -``` -hab sup secret generate -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - - ---- - -### hab sup secret generate-tls - -Generate a private key and certificate for the Supervisor's Control Gateway TLS connection - -**USAGE** - -``` -hab sup secret generate-tls [OPTIONS] --subject-alternative-name -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` ---path The directory to store the generated private key and certificate [default: /hab/cache/keys/ctl] - - --subject-alternative-name The DNS name to use in the certificates subject alternative name extension -``` - - - - ---- - -### hab sup sh - -Start an interactive Bourne-like shell - -**USAGE** - -``` -hab sup sh -``` - -**FLAGS** - -``` --h, --help Prints help information -``` - - - - - ---- - -### hab sup status - -Query the status of Habitat services - -**USAGE** - -``` -hab sup status [OPTIONS] [PKG_IDENT] -``` - -**FLAGS** - -``` --h, --help Prints help information -``` - -**OPTIONS** - -``` --r, --remote-sup Address to a remote Supervisor's Control Gateway [default: 127.0.0.1:9632] -``` - -**ARGS** - -``` - A package identifier (ex: core/redis, core/busybox-static/1.42.2) -``` - - - ---- - -### hab sup term - -Gracefully terminate the Habitat Supervisor and all of its running services - -**USAGE** - -``` -hab sup term -``` - -**FLAGS** - -``` --h, --help Prints help information -``` - - - - - ---- - -## hab supportbundle - -Create a tarball of Habitat Supervisor data to send to support - -**USAGE** - -``` -hab supportbundle -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - - ---- - -## hab svc - -Commands relating to Habitat services - -**USAGE** - -``` -hab svc -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab svc key](#hab-svc-key) | Commands relating to Habitat service keys | -| [hab svc load](#hab-svc-load) | Load a service to be started and supervised by Habitat from a package identifier. If an installed package doesn't satisfy the given package identifier, a suitable package will be installed from Builder | -| [hab svc start](#hab-svc-start) | Start a loaded, but stopped, Habitat service | -| [hab svc status](#hab-svc-status) | Query the status of Habitat services | -| [hab svc stop](#hab-svc-stop) | Stop a running Habitat service | -| [hab svc unload](#hab-svc-unload) | Unload a service loaded by the Habitat Supervisor. If the service is running it will additionally be stopped | -| [hab svc update](#hab-svc-update) | Update how the Supervisor manages an already-running service. Depending on the given changes, they may be able to be applied without restarting the service | ---- - -### hab svc key - -Commands relating to Habitat service keys - -**USAGE** - -``` -hab svc key -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab svc key generate](#hab-svc-key-generate) | Generates a Habitat service key | ---- - -### hab svc key generate - -Generates a Habitat service key - -**USAGE** - -``` -hab svc key generate [OPTIONS] [ORG] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` ---cache-key-path Cache for creating and searching for encryption keys [env: HAB_CACHE_KEY_PATH=] [default: /hab/cache/keys] -``` - -**ARGS** - -``` - Target service group service.group[@organization] (ex: redis.default or foo.default@bazcorp) - The service organization -``` - - - ---- - -### hab svc load - -Load a service to be started and supervised by Habitat from a package identifier. If an installed package doesn't - -**USAGE** - -``` -hab svc load [FLAGS] [OPTIONS] -``` - -**FLAGS** - -``` --f, --force Load or reload an already loaded service. If the service was previously loaded and running this operation will also restart the service --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` ---bind ... One or more service groups to bind to a configuration - --binding-mode Governs how the presence or absence of binds affects service startup [default: strict] [possible values: strict, relaxed] --u, --url Specify an alternate Builder endpoint. If not specified, the value will be taken from the HAB_BLDR_URL environment variable if defined. (default: https://bldr.habitat.sh) - --channel Receive updates from the specified release channel [default: stable] - - --config-from Use the package config from this path rather than the package itself - - --group The service group with shared config and topology [default: default] - --i, --health-check-interval The interval in seconds on which to run health checks [default: 30] - --r, --remote-sup Address to a remote Supervisor's Control Gateway [default: 127.0.0.1:9632] - - --shutdown-timeout The delay in seconds after sending the shutdown signal to wait before killing the service process - --s, --strategy The update strategy [default: none] [possible values: none, at-once, rolling] - --t, --topology Service topology [possible values: standalone, leader] - --update-condition The condition dictating when this service should update [default: latest] [possible values: latest, track- channel] -``` - -**ARGS** - -``` - A package identifier (ex: core/redis, core/busybox-static/1.42.2) -``` - - - ---- - -### hab svc start - -Start a loaded, but stopped, Habitat service - -**USAGE** - -``` -hab svc start [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --r, --remote-sup Address to a remote Supervisor's Control Gateway [default: 127.0.0.1:9632] -``` - -**ARGS** - -``` - A package identifier (ex: core/redis, core/busybox-static/1.42.2) -``` - - - ---- - -### hab svc status - -Query the status of Habitat services - -**USAGE** - -``` -hab svc status [OPTIONS] [PKG_IDENT] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --r, --remote-sup Address to a remote Supervisor's Control Gateway [default: 127.0.0.1:9632] -``` - -**ARGS** - -``` - A package identifier (ex: core/redis, core/busybox-static/1.42.2) -``` - - - ---- - -### hab svc stop - -Stop a running Habitat service - -**USAGE** - -``` -hab svc stop [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --r, --remote-sup Address to a remote Supervisor's Control Gateway [default: 127.0.0.1:9632] - - --shutdown-timeout The delay in seconds after sending the shutdown signal to wait before killing the service process -``` - -**ARGS** - -``` - A package identifier (ex: core/redis, core/busybox-static/1.42.2) -``` - - - ---- - -### hab svc unload - -Unload a service loaded by the Habitat Supervisor. If the service is running it will additionally be stopped - -**USAGE** - -``` -hab svc unload [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` --r, --remote-sup Address to a remote Supervisor's Control Gateway [default: 127.0.0.1:9632] - - --shutdown-timeout The delay in seconds after sending the shutdown signal to wait before killing the service process -``` - -**ARGS** - -``` - A package identifier (ex: core/redis, core/busybox-static/1.42.2) -``` - - - ---- - -### hab svc update - -Update how the Supervisor manages an already-running service. Depending on the given changes, they may be able to be - -**USAGE** - -``` -hab svc update [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` ---bind ... One or more service groups to bind to a configuration - --binding-mode Governs how the presence or absence of binds affects service startup [possible values: strict, relaxed] - --u, --url Specify an alternate Builder endpoint - --channel Receive updates from the specified release channel - --group The service group with shared config and topology --i, --health-check-interval The interval in seconds on which to run health checks --r, --remote-sup Address to a remote Supervisor's Control Gateway [default: 127.0.0.1:9632] - - --shutdown-timeout The delay in seconds after sending the shutdown signal to wait before killing the service process - --s, --strategy The update strategy [possible values: none, at-once, rolling] --t, --topology Service topology [possible values: standalone, leader] - --update-condition The condition dictating when this service should update [possible values: latest, track-channel] -``` - -**ARGS** - -``` - A package identifier (ex: core/redis, core/busybox-static/1.42.2) -``` - - - ---- - -## hab user - -Commands relating to Habitat users - -**USAGE** - -``` -hab user -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab user key](#hab-user-key) | Commands relating to Habitat user keys | ---- - -### hab user key - -Commands relating to Habitat user keys - -**USAGE** - -``` -hab user key -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - - - - -**SUBCOMMANDS** - -| Command | Description | -| ------- | ----------- | -| [hab user key generate](#hab-user-key-generate) | Generates a Habitat user key | ---- - -### hab user key generate - -Generates a Habitat user key - -**USAGE** - -``` -hab user key generate [OPTIONS] -``` - -**FLAGS** - -``` --h, --help Prints help information --V, --version Prints version information -``` - -**OPTIONS** - -``` ---cache-key-path Cache for creating and searching for encryption keys [env: HAB_CACHE_KEY_PATH=] [default: /hab/cache/keys] -``` - -**ARGS** - -``` - Name of the user key -``` - - - ---- - diff --git a/content/habitat/install_habitat.md b/content/habitat/install_habitat.md new file mode 100644 index 0000000000..8c952a0471 --- /dev/null +++ b/content/habitat/install_habitat.md @@ -0,0 +1,4 @@ ++++ +layout = "redirect" +redirect_url = "https://docs.chef.io/habitat/latest/install/" ++++ diff --git a/content/habitat/pkg_promote.md b/content/habitat/pkg_promote.md new file mode 100644 index 0000000000..6159ab39d5 --- /dev/null +++ b/content/habitat/pkg_promote.md @@ -0,0 +1,4 @@ ++++ +layout = "redirect" +redirect_url = "https://docs.chef.io/habitat/latest/packages/pkg_promote/" ++++ diff --git a/content/habitat/plan_variables.md b/content/habitat/plan_variables.md new file mode 100644 index 0000000000..ccd05a77a0 --- /dev/null +++ b/content/habitat/plan_variables.md @@ -0,0 +1,4 @@ ++++ +layout = "redirect" +redirect_url = "https://docs.chef.io/habitat/latest/reference/plan_variables" ++++ diff --git a/content/habitat/scaffolding.md b/content/habitat/scaffolding.md new file mode 100644 index 0000000000..db1da32004 --- /dev/null +++ b/content/habitat/scaffolding.md @@ -0,0 +1,4 @@ ++++ +layout = "redirect" +redirect_url = "https://docs.chef.io/habitat/latest/plans/scaffolding" ++++ diff --git a/content/habitat/service_group_updates.md b/content/habitat/service_group_updates.md new file mode 100644 index 0000000000..fe857dfd10 --- /dev/null +++ b/content/habitat/service_group_updates.md @@ -0,0 +1,4 @@ ++++ +layout = "redirect" +redirect_url = "https://docs.chef.io/habitat/latest/services/service_group_updates/" ++++ diff --git a/content/habitat/service_groups.md b/content/habitat/service_groups.md new file mode 100644 index 0000000000..3fa3a2a204 --- /dev/null +++ b/content/habitat/service_groups.md @@ -0,0 +1,4 @@ ++++ +layout = "redirect" +redirect_url = "https://docs.chef.io/habitat/latest/services/service_groups/" ++++ diff --git a/content/habitat/service_templates.md b/content/habitat/service_templates.md deleted file mode 100644 index 8e8995c4e0..0000000000 --- a/content/habitat/service_templates.md +++ /dev/null @@ -1,145 +0,0 @@ -+++ -title = "Service Template Data" - -date = 2025-09-05T15:46:37.742Z -draft = false - -[menu] - [menu.habitat] - title = "Service Template Data" - identifier = "habitat/reference/service_templates Service Template Data" - parent = "habitat/reference" -+++ - - - -The following settings can be used during a Chef Habitat service's lifecycle. This means that you can use these settings in any of the plan hooks, such as `init`, or `run`, and also in any templatized configuration file for your application or service. - -These configuration settings are referenced using the [Handlebars.js](https://github.com/wycats/handlebars.js/) version of [Mustache-style](https://mustache.github.io/mustache.5.html) tags. - - -## sys - -System information - -| Property | Type | Description | -| -------- | ---- | ----------- | -| ctl_gateway_ip | string | Listening address for Supervisor's Control Gateway. | -| ctl_gateway_port | integer | Listening port for Supervisor's Control Gateway. | -| gossip_ip | string | Listening address for Supervisor's gossip connection. | -| gossip_port | integer | Listening port for Supervisor's gossip connection. | -| hostname | string | The hostname of the running service. | -| http_gateway_ip | string | Listening address for Supervisor's HTTP gateway. | -| http_gateway_port | integer | Listening port for Supervisor's HTTP gateway. | -| ip | string | The IP address of the running service. | -| member_id | string | The member's Supervisor ID, e.g., `3d1e73ff19464a27aea3cdc5c2243f74` | -| permanent | boolean | Set to true if a Supervisor is being used as a permanent peer, to increase Ring network traffic stability. | -| version | string | Version of the Habitat Supervisor, e.g., `0.54.0/20180221023448` | - -## pkg - -Details about the package currently running the service - -| Property | Type | Description | -| -------- | ---- | ----------- | -| ident | string | The fully-qualified identifier of the running package, e.g., `core/redis/3.2.4/20170514150022` | -| origin | string | The origin of the Habitat package | -| name | string | The name of the Habitat package | -| version | string | The version of the Habitat package | -| release | string | The release of the Habitat package | -| deps | array | An array of runtime dependencies for your package based on the `pkg_deps` setting in a plan | -| env | object | The runtime environment of your package, mirroring the contents of the `RUNTIME_ENVIRONMENT` metadata file. The `PATH` variable is set, containing all dependencies of your package, as well as any other runtime environment variables that have been set by the package. Individual variables can be accessed directly, like `{{pkg.env.PATH}}` (the keys are case sensitive). | -| exposes | array | The array of ports to expose for an application or service. This value is pulled from the pkg_exposes setting in a plan. | -| exports | object | A map of export key to internal configuration value key (i.e., the contents of `pkg_exports` in your plan). The key is what external services consume. The value is a key in your `default.toml` file that corresponds to the data being exported. | -| path | string | The location where the package is installed locally, e.g., `/hab/pkgs/core/redis/3.2.4/20170514150022`. Note that this is _not_ a `PATH` environment variable; for that, please see the `env` key above. | -| svc_path | string | The root location of the source files for the Habitat service, e.g., `/hab/svc/redis`. | -| svc_config_path | string | The location of any templated configuration files for the Habitat service, e.g., `/hab/svc/redis/config`. | -| svc_data_path | string | The location of any data files for the Habitat service, e.g., `/hab/svc/redis/data`. | -| svc_files_path | string | The location of any gossiped configuration files for the Habitat service, e.g., `/hab/svc/redis/files`. | -| svc_static_path | string | The location of any static content for the Habitat service, e.g., `/hab/svc/redis/static`. | -| svc_var_path | string | The location of any variable state data for the Habitat service, e.g., `/hab/svc/redis/var`. | -| svc_pid_file | string | The location of the Habitat service pid file, e.g., `/hab/svc/redis/PID`. | -| svc_run | string | The location of the rendered run hook for the Habitat service, e.g., `/hab/svc/redis/run`. | -| svc_user | string | The value of `pkg_svc_user` specified in a plan. | -| svc_group | string | The value of `pkg_svc_group` specified in a plan. | - -## cfg - -These are settings defined in your templatized configuration file. The values for those settings are pulled from the `default.toml` file included in your package. - -## svc - -Information about the current service's service group - -| Property | Type | Description | -| -------- | ---- | ----------- | -| service | string | The name of the service. If the service is running from the package `core/redis`, the value will be `redis`. | -| group | string | The group portion of the service's complete group name. In the group name `redis.default`, the group's value is `default`. | -| org | string | The organization portion of a service group specification. Unused at this time. | -| election_is_running | boolean | Whether a leader election is currently running for this service | -| election_is_no_quorum | boolean | Whether there is quorum for a leader election for this service | -| election_is_finished | boolean | Whether a leader election for this service has finished | -| update_election_is_running | boolean | Whether an update leader election is currently running for this service | -| update_election_is_no_quorum | boolean | Whether there is quorum for an update leader election for this service | -| update_election_is_finished | boolean | Whether an update leader election for this service has finished | -| me | [svc_member](#svc_member) | An object that provides information about the service running on the local Supervisor | -| first | [svc_member](#svc_member) | The first member of this service group, or the leader, if running in a leader topology | -| members | array | All active members (`alive` and `suspect`) of the service group, across the entire ring. As of 0.56.0, does _not_ include `departed` or `confirmed` members | -| leader | [svc_member](#svc_member) | The current leader of the service group, if any (`null` otherwise) | -| update_leader | [svc_member](#svc_member) | The current update_leader of the service group, if any (`null` otherwise) | - -## bind - -Exposes information about the service groups this service is bound to. Each key is the name of a bind, while each value is one of the objects described below - -| Property | Type | Description | -| -------- | ---- | ----------- | -| first | [svc_member](#svc_member) | The first member of this service group. If the group is running in a leader topology, this will also be the leader. | -| leader | [svc_member](#svc_member) | The current leader of this service group, if running in a leader topology | -| members | array | All active members (`alive` and `suspect`) of the service group, across the entire ring. As of 0.56.0, does _not_ include `departed` or `confirmed` members | - -## Reference Objects - -Some of the template expressions referenced above return objects of a specific shape; for example, the `svc.me` and `svc.first` expressions return "service member" objects, and the `pkg` property of a service member returns a "package identifier" object. These are defined below. - -## package_identifier - -A Habitat package identifier, split apart into its constituent components - -| Property | Type | Description | -| -------- | ---- | ----------- | -| origin | string | The origin of the Habitat package | -| name | string | The name of the Habitat package | -| version | string | The version of the Habitat package | -| release | string | The release of the Habitat package | - -## svc_member - -Represents a member of a service group - -| Property | Type | Description | -| -------- | ---- | ----------- | -| member_id | string | the member's Supervisor id, e.g., 3d1e73ff19464a27aea3cdc5c2243f74 | -| alive | boolean | Whether this member is considered alive and connected to the ring, from a network perspective. | -| suspect | boolean | Whether this member is considered "suspect", or possibly unreachable, from a network perspective. | -| confirmed | boolean | Whether this member is confirmed dead / unreachable, from a network perspective. | -| departed | boolean | Whether this member has been departed from the ring (i.e., permanently gone, never to return). | -| election_is_running | boolean | Whether a leader election is currently running for this service | -| election_is_no_quorum | boolean | Whether there is quorum for a leader election for this service | -| election_is_finished | boolean | Whether a leader election for this service has finished | -| update_election_is_running | boolean | Whether an update leader election is currently running for this service | -| update_election_is_no_quorum | boolean | Whether there is quorum for an update leader election for this service | -| update_election_is_finished | boolean | Whether an update leader election for this service has finished | -| leader | boolean | Whether this member is the leader in the service group (only meaningful in a leader topology) | -| follower | boolean | Whether this member is a follower in the service group (only meaningful in a leader topology) | -| update_leader | boolean | Whether this member is the update leader in the service group (only meaningful in a leader topology) | -| update_follower | boolean | Whether this member is an update follower in the service group (only meaningful in a leader topology) | -| pkg | [package_identifier](#package_identifier) | The identifier of the release the member is running | -| pkg_incarnation | integer | Incarnation number associated with this package update | -| package | string | The package identifier | -| sys | object | An abbreviated version of the top-level {{sys}} object, containing networking information for the member. | -| cfg | object | The configuration the member is currently exporting. This is constrained by what is defined in `pkg_exports`, where the values are replaced with the current values (e.g., taking into account things like user.toml, gossiped configuration values, etc.) | -| persistent | boolean | A misspelling of `permanent`; indicates whether a member is a permanent peer or not | -| service | string | The name of the service. If the service is running from the package `core/redis`, the value will be `redis`. | -| group | string | The group portion of the service's complete group name. In the group name `redis.default`, the group's value is `default`. | -| org | string | The organization portion of a service group specification. Unused at this time. | diff --git a/content/habitat/service_updates.md b/content/habitat/service_updates.md new file mode 100644 index 0000000000..89632c2b88 --- /dev/null +++ b/content/habitat/service_updates.md @@ -0,0 +1,4 @@ ++++ +layout = "redirect" +redirect_url = "https://docs.chef.io/habitat/latest/services/service_updates/" ++++ diff --git a/content/habitat/sup.md b/content/habitat/sup.md new file mode 100644 index 0000000000..bfbef317a1 --- /dev/null +++ b/content/habitat/sup.md @@ -0,0 +1,4 @@ ++++ +layout = "redirect" +redirect_url = "https://docs.chef.io/habitat/latest/sup/" ++++ diff --git a/content/habitat/supported_packages/_index.md b/content/habitat/supported_packages/_index.md new file mode 100644 index 0000000000..e547ce1896 --- /dev/null +++ b/content/habitat/supported_packages/_index.md @@ -0,0 +1,5 @@ ++++ +title = "Chef Habitat supported packages" +list_pages = true +linkTitle = "Supported Habitat packages" ++++ \ No newline at end of file diff --git a/content/habitat/supported_packages/core_base_2025.md b/content/habitat/supported_packages/core_base_2025.md new file mode 100644 index 0000000000..4503351ead --- /dev/null +++ b/content/habitat/supported_packages/core_base_2025.md @@ -0,0 +1,682 @@ ++++ +title = "Habitat core packages in the base-2025 channel" + +[menu.habitat] + title = "core base-2025 packages" + identifier = "habitat/supported_packages/base-2025" + parent = "habitat/supported_packages" ++++ + + + +## Linux x86-64 architecture + +| Sl No | Origin | Package Name | Package Version | +| ----- | ------ | --------------------- | -------------------- | +| 1 | core | 7zip | 17.06 | +| 2 | core | acl | 2.3.2 | +| 3 | core | alex | 3.5.3.0 | +| 4 | core | alsa-lib | 1.2.11 | +| 5 | core | apr | 1.7.4 | +| 6 | core | apr-util | 1.6.3 | +| 7 | core | attr | 2.5.2 | +| 8 | core | autoconf | 2.72 | +| 9 | core | autogen | 5.18.16 | +| 10 | core | automake | 1.17 | +| 11 | core | avisynthplus | 3.7.5 | +| 12 | core | aws-cli | 2.27.36 | +| 13 | core | bash | 5.2.37 | +| 14 | core | bash-static | 5.2.37 | +| 15 | core | bats | 1.8.2 | +| 16 | core | bc | 7.0.3 | +| 17 | core | bdwgc | 8.2.6 | +| 18 | core | bind | 9.18.37 | +| 19 | core | binutils | 2.44 | +| 20 | core | bison | 3.8.2 | +| 21 | core | boost | 1.85.0 | +| 22 | core | buildah | 1.40.1 | +| 23 | core | bundler | 2.5.19 | +| 24 | core | busybox | 1.36.1 | +| 25 | core | busybox-static | 1.36.1 | +| 26 | core | bzip2 | 1.0.8 | +| 27 | core | cabal-install | 3.12.1.0 | +| 28 | core | cacerts | 2025.05.20 | +| 29 | core | cairo | 1.18.0 | +| 30 | core | certstrap | 1.3.0 | +| 31 | core | check | 0.15.2 | +| 32 | core | cmake | 4.0.3 | +| 33 | core | coreutils | 9.7 | +| 34 | core | corretto | 11.0.23.9.1 | +| 35 | core | cpanminus | 1.7047 | +| 36 | core | cunit | 3.2.7 | +| 37 | core | curl | 8.14.1 | +| 38 | core | cyrus-sasl | 2.1.28 | +| 39 | core | db | 5.3.28 | +| 40 | core | dbus | 1.14.10 | +| 41 | core | dejagnu | 1.6.3 | +| 42 | core | devicemapper | 2.03.30 | +| 43 | core | dex | 2.38.0 | +| 44 | core | diffutils | 3.11 | +| 45 | core | docker | 26.0.0 | +| 46 | core | dotnet-core | 8.0.8 | +| 47 | core | dotnet-core-sdk | 8.0.402 | +| 48 | core | doxygen | 1.11.0 | +| 49 | core | dpkg | 1.22.20 | +| 50 | core | e2fsprogs | 1.47.2 | +| 51 | core | elfutils | 0.193 | +| 52 | core | elixir | 1.17.3 | +| 53 | core | erlang26 | 26.2.5.12 | +| 54 | core | expat | 2.7.1 | +| 55 | core | expect | 5.45.4 | +| 56 | core | ffmpeg | 7.0.2 | +| 57 | core | file | 5.46 | +| 58 | core | findutils | 4.10.0 | +| 59 | core | firejail | 0.9.74 | +| 60 | core | fixesproto | 5 | +| 61 | core | flex | 2.6.4 | +| 62 | core | fontconfig | 2.15.0 | +| 63 | core | freetype | 2.13.2 | +| 64 | core | fribidi | 1.0.15 | +| 65 | core | gawk | 5.3.1 | +| 66 | core | gcc | 14.3.0 | +| 67 | core | gcc-base | 14.3.0 | +| 68 | core | gcc-libs | 14.3.0 | +| 69 | core | gdal | 3.11.0 | +| 70 | core | gdbm | 1.24 | +| 71 | core | gecode3 | 3.7.3 | +| 72 | core | gecode6 | 6.2.0 | +| 73 | core | geos | 3.13.1 | +| 74 | core | gettext | 0.24 | +| 75 | core | ghc | 9.10.2 | +| 76 | core | giflib | 5.2.1 | +| 77 | core | git | 2.49.0 | +| 78 | core | glib | 2.81.0 | +| 79 | core | glibc | 2.41 | +| 80 | core | gmp | 6.3.0 | +| 81 | core | gnupg | 2.4.5 | +| 82 | core | gnutls | 3.7.11 | +| 83 | core | go1_19 | 1.19.13 | +| 84 | core | go1_21 | 1.21.9 | +| 85 | core | go1_22 | 1.22.12 | +| 86 | core | go1_23 | 1.23.6 | +| 87 | core | go1_24 | 1.24.4 | +| 88 | core | gperf | 3.1 | +| 89 | core | gpgme | 1.23.2 | +| 90 | core | grep | 3.11 | +| 91 | core | groff | 1.23.0 | +| 92 | core | grpcurl | 1.9.3 | +| 93 | core | guile | 2.2.7 | +| 94 | core | gzip | 1.14 | +| 95 | core | happy | 1.20.1.1 | +| 96 | core | haproxy | 2.8.15 | +| 97 | core | harfbuzz | 9.0.0 | +| 98 | core | iana-etc | 20250123 | +| 99 | core | icu | 72.1 | +| 100 | core | inetutils | 2.6 | +| 101 | core | inputproto | 2.3.2 | +| 102 | core | iproute2 | 6.15.0 | +| 103 | core | iptables | 1.8.11 | +| 104 | core | isl | 0.25 | +| 105 | core | jbigkit | 2.1 | +| 106 | core | jq-static | 1.8.0 | +| 107 | core | json-c | 0.18 | +| 108 | core | jsoncpp | 1.9.5 | +| 109 | core | kbproto | 1.0.7 | +| 110 | core | krb5 | 1.21.2 | +| 111 | core | lcms2 | 2.16 | +| 112 | core | lerc | 4.0.0 | +| 113 | core | less | 668 | +| 114 | core | libaio | 0.3.113 | +| 115 | core | libarchive | 3.8.1 | +| 116 | core | libassuan | 2.5.5 | +| 117 | core | libatomic_ops | 7.8.2 | +| 118 | core | libb2 | 0.98.1 | +| 119 | core | libbsd | 0.12.2 | +| 120 | core | libcap | 2.73 | +| 121 | core | libdeflate | 1.15 | +| 122 | core | libdrm | 2.4.122 | +| 123 | core | libedit | 20250104-3.1 | +| 124 | core | libevent | 2.1.12 | +| 125 | core | libffi | 3.4.7 | +| 126 | core | libgcrypt | 1.10.3 | +| 127 | core | libgeotiff | 1.7.1 | +| 128 | core | libgpg-error | 1.46 | +| 129 | core | libice | 1.1.1 | +| 130 | core | libiconv | 1.18 | +| 131 | core | libidn2 | 2.3.3 | +| 132 | core | libjpeg-turbo | 3.1.1 | +| 133 | core | libksba | 1.6.7 | +| 134 | core | libmd | 1.1.0 | +| 135 | core | libmpc | 1.3.1 | +| 136 | core | libnl | 3.2.25 | +| 137 | core | libossp-uuid | 1.6.2 | +| 138 | core | libpcap | 1.10.4 | +| 139 | core | libpciaccess | 0.17 | +| 140 | core | libpcre2 | 10.42 | +| 141 | core | libpng | 1.6.37 | +| 142 | core | libpsl | 0.21.1 | +| 143 | core | libpthread-stubs | 0.4 | +| 144 | core | librhash | 1.4.3 | +| 145 | core | libseccomp | 2.5.4 | +| 146 | core | libsm | 1.2.4 | +| 147 | core | libsodium | 1.0.18 | +| 148 | core | libtasn1 | 4.19.0 | +| 149 | core | libtiff | 4.5.0 | +| 150 | core | libtool | 2.5.4 | +| 151 | core | libunistring | 1 | +| 152 | core | libunwind | 1.6.2 | +| 153 | core | libuv | 1.51.0 | +| 154 | core | libwebp | 1.2.4 | +| 155 | core | libxau | 1.0.12 | +| 156 | core | libxcb | 1.14 | +| 157 | core | libxcrypt | 4.4.38 | +| 158 | core | libxdmcp | 1.1.5 | +| 159 | core | libxext | 1.3.6 | +| 160 | core | libxfixes | 5.0.3 | +| 161 | core | libxi | 1.7.10 | +| 162 | core | libxml2 | 2.14.3 | +| 163 | core | libxrender | 0.9.12 | +| 164 | core | libxslt | 1.1.43 | +| 165 | core | libxtst | 1.2.5 | +| 166 | core | libyaml | 0.2.5 | +| 167 | core | linux-headers | 5.19.8 | +| 168 | core | linux-headers-musl | 4.19.88-2 | +| 169 | core | llvm | 18.1.6 | +| 170 | core | local-lib | 2.000029 | +| 171 | core | lsof | 4.99.3 | +| 172 | core | lttng-ust | 2.13.8 | +| 173 | core | lua | 5.4.6 | +| 174 | core | lz4 | 1.10.0 | +| 175 | core | lzip | 1.25 | +| 176 | core | lzo | 2.1 | +| 177 | core | lzop | 1.04 | +| 178 | core | m4 | 1.4.19 | +| 179 | core | make | 4.4.1 | +| 180 | core | maven | 3.9.7 | +| 181 | core | memcached | 1.6.38 | +| 182 | core | meson | 1.7.0 | +| 183 | core | mg | 20250523 | +| 184 | core | minio | 2025-05-24T17-08-30Z | +| 185 | core | mongodb | 8.0.10 | +| 186 | core | mpfr | 4.2.1 | +| 187 | core | musl | 1.2.5 | +| 188 | core | mysql-client | 8.4.0 | +| 189 | core | nasm | 2.16.03 | +| 190 | core | ncurses | 6.5 | +| 191 | core | netavark | 1.12.2 | +| 192 | core | netcat | 0.7.1 | +| 193 | core | netcat-openbsd | 1.229 | +| 194 | core | nettle | 3.9 | +| 195 | core | net-tools | 2.1 | +| 196 | core | nghttp2 | 1.65.0 | +| 197 | core | nginx | 1.28.0 | +| 198 | core | ninja | 1.13.0 | +| 199 | core | node | 22.17.0 | +| 200 | core | npth | 1.7 | +| 201 | core | nspr | 4.35 | +| 202 | core | nss | 3.102 | +| 203 | core | nss-myhostname | 0.3 | +| 204 | core | numactl | 2.0.19 | +| 205 | core | oniguruma | 6.9.8 | +| 206 | core | openjpeg | 2.5.2 | +| 207 | core | openldap | 2.6.10 | +| 208 | core | openssh | 10.0p1 | +| 209 | core | openssl | 3.5.0 | +| 210 | core | openssl-musl | 3.5.0 | +| 211 | core | opentofu | 1.9.0 | +| 212 | core | p11-kit | 0.25.5 | +| 213 | core | pango | 1.56.3 | +| 214 | core | parallel | 20250522 | +| 215 | core | patch | 2.7.6 | +| 216 | core | patchelf | 0.18.0 | +| 217 | core | pcre2 | 10.42 | +| 218 | core | perl | 5.40.1 | +| 219 | core | pester | 5.5.0 | +| 220 | core | pixman | 0.43.4 | +| 221 | core | pkg-config | 0.29.2 | +| 222 | core | popt | 1.19 | +| 223 | core | postgis3 | 3.3.2 | +| 224 | core | postgresql13 | 13.22 | +| 225 | core | postgresql13-client | 13.22 | +| 226 | core | postgresql14 | 14.18 | +| 227 | core | postgresql14-client | 14.18 | +| 228 | core | postgresql15 | 15.13 | +| 229 | core | postgresql15-client | 15.13 | +| 230 | core | postgresql17 | 17.5 | +| 231 | core | postgresql17-client | 17.5 | +| 232 | core | postgresql-with-ext15 | 15.13 | +| 233 | core | powershell | 7.4.3 | +| 234 | core | procps-ng | 4.0.5 | +| 235 | core | proj | 9.6.1 | +| 236 | core | prometheus | 2.53.2 | +| 237 | core | protobuf | 21.12 | +| 238 | core | protobuf-c | 1.4.1 | +| 239 | core | protobuf-cpp | 3.21.12 | +| 240 | core | protobuf-rust | 1.7.5 | +| 241 | core | psmisc | 23.7 | +| 242 | core | python | 3.13.4 | +| 243 | core | raml2html | 7.8.0 | +| 244 | core | re2c | 3 | +| 245 | core | readline | 8.2.13 | +| 246 | core | recordproto | 1.14.2 | +| 247 | core | redis | 7.0.8 | +| 248 | core | renderproto | 0.11.1 | +| 249 | core | rpm | 4.18.2 | +| 250 | core | rsync | 3.4.1 | +| 251 | core | ruby3_1 | 3.1.6 | +| 252 | core | ruby3_3 | 3.3.0 | +| 253 | core | ruby3_4 | 3.4.2 | +| 254 | core | runc | 1.1.14 | +| 255 | core | runit | 2.2.0 | +| 256 | core | rust | 1.89.0 | +| 257 | core | scaffolding-base | 0.1.0 | +| 258 | core | scaffolding-go | 0.2.0 | +| 259 | core | sccache | 0.8.1 | +| 260 | core | scons | 4.6.0 | +| 261 | core | sed | 4.9 | +| 262 | core | shadow | 4.17.4 | +| 263 | core | shellcheck | 0.10.0 | +| 264 | core | sqitch | 1.4.1 | +| 265 | core | sqlite | 3.50.4 | +| 266 | core | strace | 6.15 | +| 267 | core | sudo | 1.9.15p5 | +| 268 | core | tar | 1.35 | +| 269 | core | tcl | 8.6.16 | +| 270 | core | texinfo | 7.2 | +| 271 | core | toml-cli | 0.2.3 | +| 272 | core | tzdata | 2025b | +| 273 | core | unzip | 6 | +| 274 | core | userspace-rcu | 0.14.0 | +| 275 | core | util-linux | 2.40.4 | +| 276 | core | util-macros | 1.20.2 | +| 277 | core | valgrind | 3.18.1 | +| 278 | core | vault | 1.19.5 | +| 279 | core | vim | 9.1.1166 | +| 280 | core | wget | 1.25.0 | +| 281 | core | wget-static | 1.25.0 | +| 282 | core | which | 2.21 | +| 283 | core | xcb-proto | 1.14 | +| 284 | core | xextproto | 7.3.0 | +| 285 | core | xlib | 1.8.12 | +| 286 | core | xproto | 7.0.31 | +| 287 | core | xtrans | 1.4.0 | +| 288 | core | xxhash | 0.8.1 | +| 289 | core | xz | 5.8.1 | +| 290 | core | yarn | 1.22.22 | +| 291 | core | zeromq | 4.3.4 | +| 292 | core | zlib | 1.3.1 | +| 293 | core | zlib-musl | 1.3.1 | +| 294 | core | zstd | 1.5.7 | + +## Linux AArch64 architecture + +| Sl No | Origin | Package Name | Package Version | +| ----- | ------ | --------------------- | -------------------- | +| 1 | core | acl | 2.3.2 | +| 2 | core | attr | 2.5.2 | +| 3 | core | autoconf | 2.72 | +| 4 | core | automake | 1.17 | +| 5 | core | aws-cli | 2.27.36 | +| 6 | core | bash | 5.2.37 | +| 7 | core | bash-static | 5.2.37 | +| 8 | core | bats | 1.8.2 | +| 9 | core | bc | 7.0.3 | +| 10 | core | binutils | 2.44 | +| 11 | core | bison | 3.8.2 | +| 12 | core | buildah | 1.40.1 | +| 13 | core | busybox | 1.36.1 | +| 14 | core | busybox-static | 1.36.1 | +| 15 | core | bzip2 | 1.0.8 | +| 16 | core | cacerts | 2025.05.20 | +| 17 | core | certstrap | 1.3.0 | +| 18 | core | cmake | 4.0.3 | +| 19 | core | coreutils | 9.7 | +| 20 | core | cpanminus | 1.7047 | +| 21 | core | cunit | 3.2.7 | +| 22 | core | curl | 8.14.1 | +| 23 | core | cyrus-sasl | 2.1.28 | +| 24 | core | db | 5.3.28 | +| 25 | core | dejagnu | 1.6.3 | +| 26 | core | dex | 2.38.0 | +| 27 | core | diffutils | 3.11 | +| 28 | core | docker | 26.0.0 | +| 29 | core | dotnet-core-sdk | 8.0.402 | +| 30 | core | e2fsprogs | 1.47.2 | +| 31 | core | erlang26 | 26.2.5.12 | +| 32 | core | expat | 2.7.1 | +| 33 | core | expect | 5.45.4 | +| 34 | core | file | 5.46 | +| 35 | core | findutils | 4.10.0 | +| 36 | core | firejail | 0.9.74 | +| 37 | core | fixesproto | 5 | +| 38 | core | flex | 2.6.4 | +| 39 | core | gawk | 5.3.1 | +| 40 | core | gcc | 14.3.0 | +| 41 | core | gcc-base | 14.3.0 | +| 42 | core | gcc-libs | 14.3.0 | +| 43 | core | gdal | 3.11.0 | +| 44 | core | gdbm | 1.24 | +| 45 | core | gecode3 | 3.7.3 | +| 46 | core | gecode6 | 6.2.0 | +| 47 | core | geos | 3.13.1 | +| 48 | core | gettext | 0.24 | +| 49 | core | giflib | 5.2.1 | +| 50 | core | git | 2.49.0 | +| 51 | core | glibc | 2.41 | +| 52 | core | gmp | 6.3.0 | +| 53 | core | gnupg | 2.4.5 | +| 54 | core | go1_19 | 1.19.13 | +| 55 | core | go1_21 | 1.21.9 | +| 56 | core | go1_22 | 1.22.12 | +| 57 | core | go1_23 | 1.23.6 | +| 58 | core | go1_24 | 1.24.4 | +| 59 | core | gperf | 3.1 | +| 60 | core | gpgme | 1.23.2 | +| 61 | core | grep | 3.11 | +| 62 | core | groff | 1.23.0 | +| 63 | core | grpcurl | 1.9.3 | +| 64 | core | gzip | 1.14 | +| 65 | core | haproxy | 2.8.15 | +| 66 | core | iana-etc | 20250123 | +| 67 | core | icu | 72.1 | +| 68 | core | inetutils | 2.6 | +| 69 | core | inputproto | 2.3.2 | +| 70 | core | isl | 0.25 | +| 71 | core | jbigkit | 2.1 | +| 72 | core | jq-static | 1.8.0 | +| 73 | core | json-c | 0.18 | +| 74 | core | jsoncpp | 1.9.5 | +| 75 | core | kbproto | 1.0.7 | +| 76 | core | krb5 | 1.21.2 | +| 77 | core | lerc | 4.0.0 | +| 78 | core | less | 668 | +| 79 | core | libarchive | 3.8.1 | +| 80 | core | libassuan | 2.5.5 | +| 81 | core | libb2 | 0.98.1 | +| 82 | core | libbsd | 0.12.2 | +| 83 | core | libcap | 2.73 | +| 84 | core | libdeflate | 1.15 | +| 85 | core | libedit | 20250104-3.1 | +| 86 | core | libevent | 2.1.12 | +| 87 | core | libffi | 3.4.7 | +| 88 | core | libgcrypt | 1.10.3 | +| 89 | core | libgeotiff | 1.7.1 | +| 90 | core | libgpg-error | 1.46 | +| 91 | core | libiconv | 1.18 | +| 92 | core | libidn2 | 2.3.3 | +| 93 | core | libjpeg-turbo | 3.1.1 | +| 94 | core | libksba | 1.6.7 | +| 95 | core | libmd | 1.1.0 | +| 96 | core | libmpc | 1.3.1 | +| 97 | core | libossp-uuid | 1.6.2 | +| 98 | core | libpcre2 | 10.42 | +| 99 | core | libpng | 1.6.37 | +| 100 | core | libpsl | 0.21.1 | +| 101 | core | libpthread-stubs | 0.4 | +| 102 | core | librhash | 1.4.3 | +| 103 | core | libseccomp | 2.5.4 | +| 104 | core | libsodium | 1.0.18 | +| 105 | core | libtiff | 4.5.0 | +| 106 | core | libtool | 2.5.4 | +| 107 | core | libunistring | 1 | +| 108 | core | libunwind | 1.6.2 | +| 109 | core | libuv | 1.51.0 | +| 110 | core | libwebp | 1.2.4 | +| 111 | core | libxau | 1.0.12 | +| 112 | core | libxcb | 1.14 | +| 113 | core | libxcrypt | 4.4.38 | +| 114 | core | libxdmcp | 1.1.5 | +| 115 | core | libxext | 1.3.6 | +| 116 | core | libxfixes | 5.0.3 | +| 117 | core | libxi | 1.7.10 | +| 118 | core | libxml2 | 2.14.3 | +| 119 | core | libxrender | 0.9.12 | +| 120 | core | libxslt | 1.1.43 | +| 121 | core | libxtst | 1.2.5 | +| 122 | core | libyaml | 0.2.5 | +| 123 | core | linux-headers | 5.19.8 | +| 124 | core | local-lib | 2.000029 | +| 125 | core | lttng-ust | 2.13.8 | +| 126 | core | lz4 | 1.10.0 | +| 127 | core | lzip | 1.25 | +| 128 | core | lzo | 2.1 | +| 129 | core | lzop | 1.04 | +| 130 | core | m4 | 1.4.19 | +| 131 | core | make | 4.4.1 | +| 132 | core | memcached | 1.6.38 | +| 133 | core | mg | 20250523 | +| 134 | core | minio | 2025-05-24T17-08-30Z | +| 135 | core | mpfr | 4.2.1 | +| 136 | core | musl | 1.2.5 | +| 137 | core | ncurses | 6.5 | +| 138 | core | netavark | 1.12.2 | +| 139 | core | netcat-openbsd | 1.229 | +| 140 | core | net-tools | 2.1 | +| 141 | core | nghttp2 | 1.65.0 | +| 142 | core | nginx | 1.28.0 | +| 143 | core | ninja | 1.13.0 | +| 144 | core | node | 22.17.0 | +| 145 | core | npth | 1.7 | +| 146 | core | nss-myhostname | 0.3 | +| 147 | core | numactl | 2.0.19 | +| 148 | core | oniguruma | 6.9.8 | +| 149 | core | openssh | 10.0p1 | +| 150 | core | openssl | 3.5.0 | +| 151 | core | opentofu | 1.9.0 | +| 152 | core | parallel | 20250522 | +| 153 | core | patch | 2.7.6 | +| 154 | core | patchelf | 0.18.0 | +| 155 | core | pcre2 | 10.42 | +| 156 | core | perl | 5.40.1 | +| 157 | core | pester | 5.5.0 | +| 158 | core | pkg-config | 0.29.2 | +| 159 | core | postgis3 | 3.3.2 | +| 160 | core | postgresql13 | 13.21 | +| 161 | core | postgresql13-client | 13.21 | +| 162 | core | postgresql14 | 14.18 | +| 163 | core | postgresql14-client | 14.18 | +| 164 | core | postgresql15 | 15.13 | +| 165 | core | postgresql15-client | 15.13 | +| 166 | core | postgresql17 | 17.5 | +| 167 | core | postgresql17-client | 17.5 | +| 168 | core | postgresql-with-ext15 | 15.13 | +| 169 | core | powershell | 7.4.3 | +| 170 | core | procps-ng | 4.0.5 | +| 171 | core | proj | 9.6.1 | +| 172 | core | protobuf | 21.12 | +| 173 | core | protobuf-c | 1.4.1 | +| 174 | core | protobuf-cpp | 3.21.12 | +| 175 | core | protobuf-rust | 1.7.5 | +| 176 | core | psmisc | 23.7 | +| 177 | core | python | 3.13.4 | +| 178 | core | raml2html | 7.8.0 | +| 179 | core | re2c | 3 | +| 180 | core | readline | 8.2.13 | +| 181 | core | recordproto | 1.14.2 | +| 182 | core | redis | 7.0.8 | +| 183 | core | renderproto | 0.11.1 | +| 184 | core | rsync | 3.4.1 | +| 185 | core | ruby3_1 | 3.1.6 | +| 186 | core | ruby3_3 | 3.3.0 | +| 187 | core | ruby3_4 | 3.4.2 | +| 188 | core | runc | 1.1.14 | +| 189 | core | runit | 2.2.0 | +| 190 | core | rust | 1.89.0 | +| 191 | core | scaffolding-base | 0.1.0 | +| 192 | core | scaffolding-go | 0.2.0 | +| 193 | core | sccache | 0.8.1 | +| 194 | core | sed | 4.9 | +| 195 | core | shadow | 4.17.4 | +| 196 | core | sqitch | 1.4.1 | +| 197 | core | sqlite | 3.50.0 | +| 198 | core | strace | 6.15 | +| 199 | core | tar | 1.35 | +| 200 | core | tcl | 8.6.16 | +| 201 | core | texinfo | 7.2 | +| 202 | core | toml-cli | 0.2.3 | +| 203 | core | tzdata | 2025b | +| 204 | core | unzip | 6 | +| 205 | core | userspace-rcu | 0.14.0 | +| 206 | core | util-linux | 2.40.4 | +| 207 | core | util-macros | 1.20.2 | +| 208 | core | valgrind | 3.18.1 | +| 209 | core | vim | 9.1.1166 | +| 210 | core | wget | 1.25.0 | +| 211 | core | which | 2.21 | +| 212 | core | xcb-proto | 1.14 | +| 213 | core | xextproto | 7.3.0 | +| 214 | core | xlib | 1.8.12 | +| 215 | core | xproto | 7.0.31 | +| 216 | core | xtrans | 1.4.0 | +| 217 | core | xxhash | 0.8.1 | +| 218 | core | xz | 5.8.1 | +| 219 | core | zeromq | 4.3.4 | +| 220 | core | zlib | 1.3.1 | +| 221 | core | zstd | 1.5.7 | + +## Darwin AArch64 architecture + +| Sl No | Origin | Package Name | Package Version | +| ----- | ------ | ------------ | --------------- | +| 1 | core | autoconf | 2.72 | +| 2 | core | automake | 1.17 | +| 3 | core | bash | 5.2.37 | +| 4 | core | bats | 1.8.2 | +| 5 | core | bzip2 | 1.0.8 | +| 6 | core | cacerts | 2025.05.20 | +| 7 | core | clang | 1.0.0 | +| 8 | core | cmake | 3.25.1 | +| 9 | core | coreutils | 9.7 | +| 10 | core | cunit | 3.2.7 | +| 11 | core | curl | 8.14.1 | +| 12 | core | dejagnu | 1.6.3 | +| 13 | core | diffutils | 3.11 | +| 14 | core | erlang | 26.2.5.12 | +| 15 | core | expat | 2.7.1 | +| 16 | core | expect | 5.45.4 | +| 17 | core | file | 5.46 | +| 18 | core | findutils | 4.10.0 | +| 19 | core | gawk | 5.3.1 | +| 20 | core | gdbm | 1.24 | +| 21 | core | gettext | 0.24 | +| 22 | core | git | 2.50.1 | +| 23 | core | grep | 3.11 | +| 24 | core | gzip | 1.14 | +| 25 | core | iana-etc | 20250123 | +| 26 | core | icu | 74.2 | +| 27 | core | jsoncpp | 1.9.5 | +| 28 | core | ld64 | 1.0.0 | +| 29 | core | less | 668 | +| 30 | core | libarchive | 3.8.1 | +| 31 | core | libb2 | 0.98.1 | +| 32 | core | libffi | 3.4.7 | +| 33 | core | libiconv | 1.18 | +| 34 | core | libidn2 | 2.3.3 | +| 35 | core | libpcre2 | 10.42 | +| 36 | core | libpsl | 0.21.1 | +| 37 | core | librhash | 1.4.3 | +| 38 | core | libsodium | 1.0.18 | +| 39 | core | libtool | 2.5.4 | +| 40 | core | libunistring | 1 | +| 41 | core | libuv | 1.51.0 | +| 42 | core | libxml2 | 2.14.3 | +| 43 | core | libyaml | 0.2.5 | +| 44 | core | lz4 | 1.10.0 | +| 45 | core | lzip | 1.25 | +| 46 | core | lzo | 2.1 | +| 47 | core | lzop | 1.04 | +| 48 | core | m4 | 1.4.19 | +| 49 | core | make | 4.4.1 | +| 50 | core | mg | 7.3 | +| 51 | core | native-rust | 1.89.0 | +| 52 | core | ncurses | 6.5 | +| 53 | core | nghttp2 | 1.65.0 | +| 54 | core | nginx | 1.28.0 | +| 55 | core | node | 22.17.0 | +| 56 | core | openssl | 3.5.0 | +| 57 | core | parallel | 20250522 | +| 58 | core | patch | 2.7.6 | +| 59 | core | pcre2 | 10.42 | +| 60 | core | perl | 5.40.1 | +| 61 | core | pkg-config | 0.29.2 | +| 62 | core | protobuf | 29.5 | +| 63 | core | python | 3.13.4 | +| 64 | core | raml2html | 7.8.0 | +| 65 | core | readline | 8.2.13 | +| 66 | core | ruby3_1 | 3.1.6 | +| 67 | core | ruby3_4 | 3.4.2 | +| 68 | core | rust | 1.89.0 | +| 69 | core | sed | 4.9 | +| 70 | core | sqlite | 3.50.4 | +| 71 | core | system | 1.0.0 | +| 72 | core | tar | 1.35 | +| 73 | core | tcl | 8.6.16 | +| 74 | core | texinfo | 7.2 | +| 75 | core | toml-cli | 0.2.3 | +| 76 | core | unzip | 6 | +| 77 | core | vim | 9.1.1166 | +| 78 | core | wget | 1.25.0 | +| 79 | core | xcode | 1.0.0 | +| 80 | core | xz | 5.8.1 | +| 81 | core | zeromq | 4.3.4 | +| 82 | core | zlib | 1.3.1 | +| 83 | core | zstd | 1.5.7 | + +## Windows x86-64 architecture + +| Sl No | Origin | Package Name | Package Version | +| ----- | ------ | ------------------------ | --------------- | +| 1 | core | 7zip | 24.09 | +| 2 | core | asciinema | 2.4.0 | +| 3 | core | aws-cli | 1.41.3 | +| 4 | core | buildkite-agent | 3.73.1 | +| 5 | core | buildkite-cli | 2.0.0 | +| 6 | core | bzip2 | 1.0.8 | +| 7 | core | cabal-install | 3.12.1.0 | +| 8 | core | cacerts | 2025.05.20 | +| 9 | core | cmake | 4.0.3 | +| 10 | core | concourse | 7.11.2 | +| 11 | core | corretto11 | 11.0.23.9.1 | +| 12 | core | docker | 26.1.4 | +| 13 | core | docker-credential-helper | 0.8.2 | +| 14 | core | dotnet-481-dev-pack | 4.8.1 | +| 15 | core | dotnet-core-sdk | 8.0.303 | +| 16 | core | ghc | 9.10.2 | +| 17 | core | git | 2.49.0 | +| 18 | core | go1_22 | 1.22.12 | +| 19 | core | go1_23 | 1.23.6 | +| 20 | core | go1_24 | 1.24.4 | +| 21 | core | innounp | 0.5 | +| 22 | core | jq-static | 1.8.0 | +| 23 | core | lessmsi | 2.0.1 | +| 24 | core | libarchive | 3.8.1 | +| 25 | core | libsodium | 1.0.20 | +| 26 | core | maven | 3.9.7 | +| 27 | core | nasm | 2.16.03 | +| 28 | core | nginx | 1.28.0 | +| 29 | core | node | 22.17.0 | +| 30 | core | nuget | 6.10.0 | +| 31 | core | openssl | 3.5.0 | +| 32 | core | openssl-fips | 3.1.2 | +| 33 | core | packer | 1.11.0 | +| 34 | core | perl | 5.41.2 | +| 35 | core | pester | 5.5.0 | +| 36 | core | postgresql15-client | 15.13 | +| 37 | core | powershell | 7.5.0 | +| 38 | core | protobuf | 3.27.3 | +| 39 | core | ps-lock | 0.1.1 | +| 40 | core | psscriptanalyzer | 1.22.0 | +| 41 | core | python | 3.13.5 | +| 42 | core | raml2html | 7.8.0 | +| 43 | core | ruby3_3-plus-devkit | 3.3.1 | +| 44 | core | ruby3_4-plus-devkit | 3.4.2 | +| 45 | core | rust | 1.89.0 | +| 46 | core | shellcheck | 0.10.0 | +| 47 | core | visual-build-tools-2022 | 17.14.7 | +| 48 | core | visual-cpp-redist-2022 | 14.44.35208.0 | +| 49 | core | windows-11-sdk | 10.0.26100 | +| 50 | core | wix | 3.14.1 | +| 51 | core | xz | 5.8.1 | +| 52 | core | yarn | 1.22.22 | +| 53 | core | zeromq | 4.3.5 | +| 54 | core | zlib | 1.3.1 | diff --git a/content/habitat/supported_packages/package_refresh_strategy.md b/content/habitat/supported_packages/package_refresh_strategy.md new file mode 100644 index 0000000000..05a2d16f5d --- /dev/null +++ b/content/habitat/supported_packages/package_refresh_strategy.md @@ -0,0 +1,245 @@ ++++ +title = "Chef Habitat package refresh strategy" + +[menu.habitat] + title = "Habitat package refresh strategy" + identifier = "habitat/supported_packages/refresh strategy" + parent = "habitat/supported_packages" + weight = 10 ++++ + + + +A Habitat package is an artifact that has the built application artifacts, lifecycle configurations, and a manifest that includes a plan file that defines the build and runtime dependencies of the application. +The package is bundled into a Habitat Artifact (`.HART`) file, which is a binary distribution of a given package built with Chef Habitat. +The package is immutable and cryptographically signed with a key so you can verify that the artifact came from where you expected it to come from. +Artifacts can be exported to run in a variety of runtimes with zero refactoring or rewriting. + +A package is defined by the package origin and package name: `/`. +For example: `core/node` + +## Habitat package support + +### Previous package support approach and limitations + +We regularly refreshed and released all Habitat packages in the core origin to the stable channel on Chef Habitat SaaS Builder. +We encouraged users to use packages from the stable channel as a best practice. Initially, we designed the stable channel for consistent stability across packages; however, this model is less effective for core libraries, which require specific lifecycle policies. +We didn't remove packages---we skipped any that we couldn't refresh due to incompatibility or build issues. + +This led to several issues: + +- Package deprecation, relegation, or major version upgrades could disrupt existing applications or installations. +- We could only include minor security fixes. + This model prevents the deprecation or removal of outdated packages and limits the inclusion of significant security fixes or major version updates. + This could lead to risks when using pinned packages, as they may not upgrade to more secure versions. + +For example, we continued to release PostgreSQL 9.3 in the core channel despite it being out of support, as removing it could disrupt existing applications. + +### Multi-channel package refresh approach + +The multi-channel package refresh approach manages Habitat package updates and lifecycles using year-based channels, for example "base-2025". These channels provide a reliable and consistent environment for users, ensuring long-term support and stability for their applications and deployments. + +- **Multiple channels**: The base-YYYY channels, where YYYY indicates the year of release, create a stable environment with the latest packages, are supported for three years, and are created every three years. For example, base-2025, base-2028, and base-2031. + + The initial base-YYYY release has breaking changes because it has major upgrades and removes end-of-life packages. + Subsequent releases within the channel maintain stability and compatibility. + +- **Update strategy**: The multi-channel approach allows you to update packages by major version in new base-YYYY channels, minimizing disruption for users who continue to point to the previous base-YYYY channel. +- **Deprecation strategy**: The multi-channel approach excludes EOL or deprecated packages from new base-YYYY releases, but those packages remain in existing base-YYYY channels, minimizing disruption for users. +- **Impact on existing channels**: The stable channel in the core origin is deprecated because it has legacy and unsupported packages. +- **Channel compatibility**: Packages in a particular channel are always compatible with all other packages within a channel. + This is applicable even for cross-origin packages. +- **Refresh with Chef Habitat**: Chef Habitat allows users to specify the channel from where a package build should happen with `--refresh-channel` or `HAB_REFRESH_CHANNEL` environment variable. +- **Sync scripts**: Sync scripts allow you to synchronize packages from Chef Habitat SaaS Builder to a user-deployed On-Prem Builder. +- **Maintenance cycles**: Each package has an associated maintenance cycle during a package refresh to identify if multiple major or minor versions for that project are available. +- **Package naming conventions**: Packages follow specific naming conventions based on their versioning schema, ensuring consistency and reliability in updates. +- **Package intake process**: If Chef Habitat users wants to have a new package added to the core origin, they can request it with Aha Ideas. If the requested package meets the support and usage thresholds, we will consider it alongside other feature requests during planning periods. + +## Chef-owned origins and supported channels + +Chef maintains the following origins and release channels: + +core +: The core origin has packages for common dependencies and compilers and is maintained by Progress Chef. + + - **base** channel always points to the latest base-YYYY channel. + This becomes the default channel when building, downloading, or installing packages from core origin. + - **base-YYYY** channel that has the latest versions of core origin packages in the base-YYYY's supported period. + - **Point-in-time** releases for versions of core packages in **base-YYYY-timestamp** channels whenever a package is updated. + - **LTS-2024 intermediate support channel named** for supporting bug fixes/CVE fixes in core origin packages required for building existing releases of Chef products. + This channel becomes EOL once existing releases of Chef products are EOL. + +chef +: The chef origin has packages of Chef products like Chef Infra Client, Chef InSpec, Chef Habitat, and Chef Automate. + + - **stable** channel has all releases of Chef products. + This becomes the default channel when building, downloading, or installing packages from chef origin. + - **base-YYYY** channel has the releases of Chef products built with the core origin dependencies from the corresponding base-YYYY channel. + The base-YYYY channel in Chef origin is supported as long as Chef products in those channels are supported. + - **Point-in-time** releases and versions of Chef products in **base-YYYY-timestamp** channels. + - **LTS-2024 intermediate support channel** for supporting bug fixes/CVE fixes in existing releases of Chef products. + This channel becomes EOL once existing releases of Chef products are EOL. + +chef-platform +: The chef-platform origin has packages of Chef 360 Platform skills. + + - **stable** channel has all releases of Chef 360 Platform skills. + This becomes the default channel when building, downloading, or installing packages from chef origin. + - **base-YYYY** channel has the releases of Chef 360 Platform skills that are built with the core origin dependencies from the corresponding base-YYYY channel. + The base-YYYY channel in chef-platform origin is supported as long as Chef 360 Platform skills in those channels are supported. + - **Point-in-time** releases and versions of Chef 360 Platform skills in **base-YYYY-timestamp** channels. + +habitat +: The habitat origin has packages for deploying Chef Habitat On-Prem Builder. + + - **stable** channel has all releases of Habitat On-Prem Builder-related packages. + - **base-YYYY** channel has the releases of On-Prem Builder-related packages that are built with the core origin dependencies from the corresponding base-YYYY channel. + - **Point-in-time** releases and versions of On-Prem Builder related packages in **base-YYYY-timestamp**. + +{{< note >}} + +- With Chef Habitat 2, we moved the Habitat binary packages to the chef origin to consistently ship all Chef product packages in the same origin. +- Subsequent major releases of Chef products like Infra Client 19 and InSpec 7 follow the new multi-channel approach---that is, releases are published in stable, base-YYYY, and point-in-time channels. + +{{< /note >}} + +## Intermediate support channel for existing Chef product releases + +Existing Chef product releases, such as Chef Infra Client 18.x and Automate 4.x, are built from core origin dependencies in the stable channel. +However, we can't update the core origin dependencies in the stable channel when providing bug fixes or CVE fixes to these product versions because of limitations in the stable channel. + +If we make bug or CVE fixes to existing Chef product versions, we source the core origin dependencies from the LTS-2024 intermediate support channel. + +You don't need to make any changes to get Chef Automate upgrades, but you must get updates to the Chef Infra Client 18.x package (`chef/chef-infra-client`) from the LTS-2024 intermediate support channel to avoid dependency conflicts. + +To do this, use the `--refresh-channel` option in Chef Habitat 2.x and above to specify release channel that you want to fetch packages from. + +## Channel support + +### Availability of packages in core origin + +| | stable | base-YYYY | base | LTS-2024 | +| --------------------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| All core packages used by Chef products | Old versions of core packages required for Habitat 1.x, Infra Client 18.x, InSpec 5.x | Latest versions of core packages required for Habitat 2.x, Infra Client 19.x, InSpec 7.x | Default channel that mirrors the latest base-YYYY channel | Has intermediate package updates required for providing bug fixes/CVE fixes in existing Chef product releases Infra Client 18.x, InSpec 7.x, Automate 4.x | +| Habitat 1.x and below | Yes | NA | NA | NA | + +### Availability of Chef product packages in chef origin + +| | stable | base-YYYY | LTS-2024 | current | +| -------------------------------------------------------------------------------- | ------------------------------- | -------------------------------------------------------------------------------------- | ------------------------- | ------- | +| Infra Client 18.x and below, InSpec 5.x and below | Yes | NA | With latest CVE/Bug fixes | NA | +| Habitat 2.x and above, Infra Client 19.x and above, InSpec 7.x and above | Yes (all versions and releases) | Yes (release built with the core origin dependencies from the corresponding base-YYYY) | NA | NA | +| Automate 4.x and below | NA | NA | NA | Yes | + +## Deprecated or end-of-life (EOL) packages + +- Packages that have reached the end of their support lifecycle are no longer maintained or updated, and are excluded from new base-YYYY releases. For example, if a package like `core/openssl11` reaches the end of its support lifecycle, it won't be included in the subsequent base-YYYY release channel. + This approach allows customers to transition to the latest base-YYYY channel at their convenience while maintaining the previous base-YYYY channel, including the older packages for those who need them. + However, the older packages won't receive support or be recommended for active use. +- This strategy ensures that deprecations don't adversely affect customers, granting the package management team the flexibility to implement significant changes without disrupting user workflows. + +## Support strategy for channels + +- When a new base-YYYY is released, the previous base-YYYY becomes deprecated. + It's available for a certain period of time so that users have sufficient time to migrate, after which it becomes EOL. +- The stable channel is deprecated when base-2025 is released. + It's available until Chef Infra Client 18 and Habitat 1.x is supported, after which it becomes EOL. + +## Change in workflow for accessing packages from Chef Habitat Builder + +- **Download packages from Chef Habitat Builder using a HAB_AUTH_TOKEN**: To download all new major releases of Chef products (Habitat 2.0, Infra 19, and others) and latest core origin packages from base-YYYY channels, you need to pass a `HAB_AUTH_TOKEN` generated using your license key (Free, Trial, Commercial) either as a flag to the [command](https://docs.chef.io/habitat/latest/reference/habitat_cli/#hab-pkg-download) or as an [environment variable](https://docs.chef.io/habitat/latest/reference/environment_variables/). +- **Accessing Builder UI using license key (Free, Trial, Commercial)** + +{{< note >}} + +For instructions on how to generate `HAB_AUTH_TOKEN` using a license key from Chef Habitat Builder UI, see the [Builder profile documentation](https://docs.chef.io/habitat/builder/saas/builder_profile/#add-a-progress-chef-license-key) + +{{< /note >}} + +### Sync packages to Chef Habitat On-Prem Builder + +We provide a sync script that updates packages on Habitat On-Prem Builder from SaaS Builder. It handles the following tasks: + +1. Performs a pre-flight check that returns a list of packages under core origin for that channel (for example, base-YYYY) that aren't created or maintained by Progress Chef. +1. If proceeding with the script: + 1. Those packages are demoted to unstable channel. + 1. Packages are downloaded from the specified channel (for example, base-2025) on Habitat SaaS Builder and uploaded to On-Prem Builder. + +## Habitat package management + +### Maintenance cycles + +Package version refreshes can be classified into the following maintenance cycles: + +1. Single major, one minor (so) +1. Single major, multiple minor (sm) +1. Multiple major, one minor (mo) +1. Multiple major, multiple minor (mm) + +### Package naming conventions + +Each package is identified by a unique string containing four sub-strings separated by a forward slash (`/`) called a packageIdent (`origin/name/version/release`). +This naming convention refers to packages in the core origin. + +When one major version of the package is supported, follow these guidelines: + +- The value of name should match the name of the project it represents. +- The plan file should be located within a directory of the same name in this repository. + +For example, a single refresh maintains one major version of glibc and as such the package name is `core/glibc` with no suffix. + +When more than one major version of the package is supported, and the project uses Semantic Versioning (SemVer): + +1. **If the project honors SemVer** (breaking changes occur in major releases) + - The value of name should match the name of the project it represents, plus the major version of the package being supported (as a suffix). + - The plan file should be located within a directory of the same name (including the suffix) in this repository. + - Example: `core/postgresql16` and/or `core/postgresql17` + +1. **If the project doesn't honor SemVer** (referred to as Romantic Versioning or RomVer) + - The value of name should match the name of the project it represents, plus the **major** and **minor** version of the package being supported (as a suffix). + - The plan file should be located within a directory of the same name (including the suffix) in this repository. + - Note: Romantic versions appear like SemVer in format but may introduce breaking changes as part of a "minor" update, resulting in version X.Y having a breaking change versus X.Z. + - Example: `core/foo3_0`, `core/foo3_1`, `core/foo3_2`, and/or `core/foo3_3` + +1. **If the project doesn't use SemVer** + - Example: builder-api, perl + - The packages are reviewed package to package and refresh to refresh. + +{{< note >}} + +Even we may alter a package name to include a major or minor version suffix, +we won't alter package versions from their project's source. +For example, if the package uses a DateVer schema in the format of _YYYYMMDD_, +we won't reformat it to _YYYY.MM.DD_. +This ensures that our automated build and detection systems can refer to the publishers' exact versions. + +{{< /note >}} + +### Support threshold + +For packages that aren't dependencies for Progress Chef tools: + +- There should be no published EOL date within the first two years of the base-YYYY support duration at the time of consideration. + If the OEM drops support or doesn't provide a fix to known vulnerabilities during the time frame, no updates are made available. +- There should be no open High or Critical CVEs for that package at the time of consideration. + If any released package has a Critical/High CVE post-release, it's fixed as part of the next minor/directed refresh. +- It should have a valid licensing model that allows Progress Chef to distribute it as a Chef Habitat package. + +### Usage threshold + +A requested package is added for backlog prioritization if it belongs to one of the categories below: + +- Commonly used development tools/programming languages +- High demand COTS + +## Guidance for using packages from different origins and channels + +- **Default channel**: While the base channel becomes the default channel for the core origin instead of the stable channel, we recommend specifying a particular base-YYYY channel. The base channel always points to the latest base-YYYY channel and using base to fetch packages could introduce breaking changes when we release a new base-YYYY channel. +- **Package pinning**: When applications have multiple dependencies, avoid pinning some dependencies to specific versions. + This can introduce conflicting versions and cause the build to fail due to each package having a fixed dependency tree. +- **Applications with cross-origin dependencies**: For users developing applications with dependencies in multiple origins, the following practices ensure compatibility: + + - If you're using the latest version of a package in the chef origin, use the "base-YYYY" channel to build and run your application without any compatibility issues. + - If you're using older package versions in the chef origin, use point-in-time channels such as "base-YYYY-timestamp" channels, to build and run your application without any compatibility issues. + +- **Custom origins for custom packages**: Progress Chef recommends that users use their own origins for custom packages within On-Prem Builder instead of using Progress Chef owned origins (core, chef, chef-platform, habitat) to ensure that those packages aren't lost when syncing their On-Prem Builder with sync scripts. diff --git a/go.mod b/go.mod index 78f279aec4..7ecb50489c 100644 --- a/go.mod +++ b/go.mod @@ -15,8 +15,6 @@ 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-20250905124722-c1a4eb639cba // indirect - github.com/habitat-sh/on-prem-builder/docs-chef-io v0.0.0-20250805192817-f8b1dae05d5e // indirect github.com/swiftype/swiftype-autocomplete-jquery v0.0.0-20190222215504-a90008d64b30 // indirect github.com/swiftype/swiftype-search-jquery v1.1.0 // indirect github.com/twitter/hogan.js v3.0.2+incompatible // indirect diff --git a/go.sum b/go.sum index 72929b2a12..c82a65e70b 100644 --- a/go.sum +++ b/go.sum @@ -22,10 +22,6 @@ 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-20250905124722-c1a4eb639cba h1:DCrplvFmHTVSFGMDo/2G3DQSounSgbAsJ1X0YhIAaR0= -github.com/habitat-sh/habitat/components/docs-chef-io v0.0.0-20250905124722-c1a4eb639cba/go.mod h1:5GKz/BtTWeTr8vdVQPkvGDQkQ+xiGWLkDsPOXhu2Ps4= -github.com/habitat-sh/on-prem-builder/docs-chef-io v0.0.0-20250805192817-f8b1dae05d5e h1:qHs6EaygFn8iNJgqeGHI6Bd1jMSynG4TijKKWfqR8N8= -github.com/habitat-sh/on-prem-builder/docs-chef-io v0.0.0-20250805192817-f8b1dae05d5e/go.mod h1:8gmm7JyOiJAbZHIpZNCP4XqgZ8RtUHaEwEi0X0AsJ4M= github.com/swiftype/swiftype-autocomplete-jquery v0.0.0-20190222215504-a90008d64b30 h1:dhqLFBINtD1rMwwd5s9INu4BkciCvQUd+r+CWUYWIB4= github.com/swiftype/swiftype-autocomplete-jquery v0.0.0-20190222215504-a90008d64b30/go.mod h1:qnxTyatkwE84LvoaQLPaLB4h5M3n6Q2z+SB/96DcAK8= github.com/swiftype/swiftype-search-jquery v1.1.0 h1:VRYyWPQtf3Vl3B5W2xQJuFVoUBlBFGQ4tOTu94b8mNU= diff --git a/netlify.toml b/netlify.toml index fa12591f7e..ff7e982bf1 100644 --- a/netlify.toml +++ b/netlify.toml @@ -92,15 +92,20 @@ # Chef Habitat redirects #### +[[redirects]] + from = "/habitat/1.6/*" + to = "https://release-1-6--chef-habitat-docs.netlify.app/habitat/1.6/:splat" + status = 200 + [[redirects]] from = "/habitat/2.0/*" to = "https://release-2-0--chef-habitat-docs.netlify.app/habitat/2.0/:splat" status = 200 [[redirects]] - from = "/habitat/1.6/*" - to = "https://release-1-6--chef-habitat-docs.netlify.app/habitat/1.6/:splat" - status = 200 + from = "/habitat/latest/*" + to = "/habitat/2.0/:splat" + status = 301 #### # Chef Infra Client redirects diff --git a/package-lock.json b/package-lock.json index da4dddaf85..0e50e10b8c 100644 --- a/package-lock.json +++ b/package-lock.json @@ -30,15 +30,13 @@ "version": "2.2.3", "resolved": "https://registry.npmjs.org/@bufbuild/protobuf/-/protobuf-2.2.3.tgz", "integrity": "sha512-tFQoXHJdkEOSwj5tRIZSPNUuXK3RaR7T1nUrPgbYX1pUbvqqaaZAsfo+NXBPsz5rZMSKVFrgK1WL8Q/MSLvprg==", - "license": "(Apache-2.0 AND BSD-3-Clause)", - "peer": true + "license": "(Apache-2.0 AND BSD-3-Clause)" }, "node_modules/@emotion/is-prop-valid": { "version": "1.2.2", "resolved": "https://registry.npmjs.org/@emotion/is-prop-valid/-/is-prop-valid-1.2.2.tgz", "integrity": "sha512-uNsoYd37AFmaCdXlg6EYD1KaPOaRWRByMCYzbKUX4+hhMfrxdVSelShywL4JVaAeM/eHUOSprYBQls+/neX3pw==", "license": "MIT", - "peer": true, "dependencies": { "@emotion/memoize": "^0.8.1" } @@ -47,15 +45,13 @@ "version": "0.8.1", "resolved": "https://registry.npmjs.org/@emotion/memoize/-/memoize-0.8.1.tgz", "integrity": "sha512-W2P2c/VRW1/1tLox0mVUalvnWXxavmv/Oum2aPsRcoDJuob75FC3Y8FbpfLwUegRcxINtGUMPq0tFCvYNTBXNA==", - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/@emotion/unitless": { "version": "0.8.1", "resolved": "https://registry.npmjs.org/@emotion/unitless/-/unitless-0.8.1.tgz", "integrity": "sha512-KOEGMu6dmJZtpadb476IsZBclKvILjopjUii3V+7MnXIQCYh8W3NgNcgwo21n9LXZX6EDIKvqfjYxXebDwxKmQ==", - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/@exodus/schemasafe": { "version": "1.3.0", @@ -116,8 +112,7 @@ "version": "4.2.5", "resolved": "https://registry.npmjs.org/@types/stylis/-/stylis-4.2.5.tgz", "integrity": "sha512-1Xve+NMN7FWjY14vLoY5tL3BVEQ/n42YLwaqJIPYhotZ9uBHt87VceMwWQpzmdEt2TNXIorIFG+YeCUUW7RInw==", - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/@types/trusted-types": { "version": "2.0.7", @@ -184,8 +179,7 @@ "version": "0.2.0", "resolved": "https://registry.npmjs.org/buffer-builder/-/buffer-builder-0.2.0.tgz", "integrity": "sha512-7VPMEPuYznPSoR21NE1zvd2Xna6c/CloiZCfcMXR1Jny6PjX0N4Nsa38zcBFo/FMK+BlA+FLKbJCQ0i2yxp+Xg==", - "license": "MIT/X11", - "peer": true + "license": "MIT/X11" }, "node_modules/call-me-maybe": { "version": "1.0.2", @@ -198,7 +192,6 @@ "resolved": "https://registry.npmjs.org/camelize/-/camelize-1.0.1.tgz", "integrity": "sha512-dU+Tx2fsypxTgtLoE36npi3UqcjSSMNYfkqgmoEhtZrraP5VWq0K7FkWVTYa8eMPtnU/G2txVsfdCJTn9uzpuQ==", "license": "MIT", - "peer": true, "funding": { "url": "https://github.com/sponsors/ljharb" } @@ -260,8 +253,7 @@ "version": "0.5.2", "resolved": "https://registry.npmjs.org/colorjs.io/-/colorjs.io-0.5.2.tgz", "integrity": "sha512-twmVoizEW7ylZSN32OgKdXRmo1qg+wT5/6C3xu5b9QsWzSFAhHLn2xd8ro0diCsKfCj1RdaTP/nrcW+vAoQPIw==", - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/core-js": { "version": "3.40.0", @@ -280,7 +272,6 @@ "resolved": "https://registry.npmjs.org/css-color-keywords/-/css-color-keywords-1.0.0.tgz", "integrity": "sha512-FyyrDHZKEjXDpNJYvVsV960FiqQyXc/LlYmsxl2BcdMb2WPx0OGRVgTg55rPSyLSNMqP52R9r8geSp7apN3Ofg==", "license": "ISC", - "peer": true, "engines": { "node": ">=4" } @@ -290,7 +281,6 @@ "resolved": "https://registry.npmjs.org/css-to-react-native/-/css-to-react-native-3.2.0.tgz", "integrity": "sha512-e8RKaLXMOFii+02mOlqwjbD00KSEKqblnpO9e++1aXS1fPQOpS1YoqdVHBqPjHNoxeF2mimzVqawm2KCbEdtHQ==", "license": "MIT", - "peer": true, "dependencies": { "camelize": "^1.0.0", "css-color-keywords": "^1.0.0", @@ -301,8 +291,7 @@ "version": "3.1.3", "resolved": "https://registry.npmjs.org/csstype/-/csstype-3.1.3.tgz", "integrity": "sha512-M1uQkMl8rQK/szD0LNhtqxIPLpimGm8sOBwU7lLnCpSbTyY3yeU1Vc7l4KT5zT4s/yOxHH5O7tIuuLOCnLADRw==", - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/debug": { "version": "4.4.0", @@ -430,7 +419,6 @@ "resolved": "https://registry.npmjs.org/has-flag/-/has-flag-4.0.0.tgz", "integrity": "sha512-EykJT/Q1KjTWctppgIAgfSO0tKVuZUjhgMr17kqTumMl6Afv3EISleU7qZUzoXDFTAHTDC4NOoG/ZxU3EvlMPQ==", "license": "MIT", - "peer": true, "engines": { "node": ">=8" } @@ -458,8 +446,7 @@ "version": "5.0.3", "resolved": "https://registry.npmjs.org/immutable/-/immutable-5.0.3.tgz", "integrity": "sha512-P8IdPQHq3lA1xVeBRi5VPqUm5HDgKnx0Ru51wZz5mjxHr5n3RWhjIpOFU7ybkUxfB+5IToy+OLaHYDBIWsv+uw==", - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/is-fullwidth-code-point": { "version": "3.0.0", @@ -474,7 +461,8 @@ "version": "3.7.1", "resolved": "https://registry.npmjs.org/jquery/-/jquery-3.7.1.tgz", "integrity": "sha512-m4avr8yL8kmFN8psrbFFFmB/If14iN5o9nw/NgnnM+kybDJpRsAynV2BsfpTYrTRysYUdADVD7CkUUizgkpLfg==", - "license": "MIT" + "license": "MIT", + "peer": true }, "node_modules/js-levenshtein": { "version": "1.1.6", @@ -657,7 +645,6 @@ } ], "license": "MIT", - "peer": true, "bin": { "nanoid": "bin/nanoid.cjs" }, @@ -812,8 +799,7 @@ "version": "1.1.1", "resolved": "https://registry.npmjs.org/picocolors/-/picocolors-1.1.1.tgz", "integrity": "sha512-xceH2snhtb5M9liqDsmEw56le376mTZkEX/jEb/RxNFyegNul7eNslCXP9FDj/Lcu0X8KEyMceP2ntpaHrDEVA==", - "license": "ISC", - "peer": true + "license": "ISC" }, "node_modules/pluralize": { "version": "8.0.0", @@ -855,7 +841,6 @@ } ], "license": "MIT", - "peer": true, "dependencies": { "nanoid": "^3.3.7", "picocolors": "^1.1.1", @@ -869,8 +854,7 @@ "version": "4.2.0", "resolved": "https://registry.npmjs.org/postcss-value-parser/-/postcss-value-parser-4.2.0.tgz", "integrity": "sha512-1NNCs6uurfkVbeXG4S8JFT9t19m45ICnif8zWLd5oPSZ50QnwMfK+H3jv408d4jw/7Bttv5axS5IiHoLaVNHeQ==", - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/prismjs": { "version": "1.30.0", @@ -1012,7 +996,6 @@ "resolved": "https://registry.npmjs.org/rxjs/-/rxjs-7.8.1.tgz", "integrity": "sha512-AA3TVj+0A2iuIoQkWEK/tqFjBq2j+6PO6Y0zJcvzLAFhEFIO3HL0vls9hWLncZbAAbK0mar7oZ4V079I/qPMxg==", "license": "Apache-2.0", - "peer": true, "dependencies": { "tslib": "^2.1.0" } @@ -1022,7 +1005,6 @@ "resolved": "https://registry.npmjs.org/sass-embedded/-/sass-embedded-1.85.0.tgz", "integrity": "sha512-x3Vv54g0jv1aPSW8OTA/0GzQCs/HMQOjIkLtZJ3Xsn/I4vnyjKbVTQmFTax9bQjldqLEEkdbvy6ES/cOOnYNwA==", "license": "MIT", - "peer": true, "dependencies": { "@bufbuild/protobuf": "^2.0.0", "buffer-builder": "^0.2.0", @@ -1062,6 +1044,102 @@ "sass-embedded-win32-x64": "1.85.0" } }, + "node_modules/sass-embedded-android-arm": { + "version": "1.85.0", + "resolved": "https://registry.npmjs.org/sass-embedded-android-arm/-/sass-embedded-android-arm-1.85.0.tgz", + "integrity": "sha512-pPBT7Ad6G8Mlao8ypVNXW2ya7I/Bhcny+RYZ/EmrunEXfhzCNp4PWV2VAweitPO9RnPIJwvUTkLc8Fu6K3nVmw==", + "cpu": [ + "arm" + ], + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/sass-embedded-android-arm64": { + "version": "1.85.0", + "resolved": "https://registry.npmjs.org/sass-embedded-android-arm64/-/sass-embedded-android-arm64-1.85.0.tgz", + "integrity": "sha512-4itDzRwezwrW8+YzMLIwHtMeH+qrBNdBsRn9lTVI15K+cNLC8z5JWJi6UCZ8TNNZr9LDBfsh5jUdjSub0yF7jg==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/sass-embedded-android-ia32": { + "version": "1.85.0", + "resolved": "https://registry.npmjs.org/sass-embedded-android-ia32/-/sass-embedded-android-ia32-1.85.0.tgz", + "integrity": "sha512-bwqKq95hzbGbMTeXCMQhH7yEdc2xJVwIXj7rGdD3McvyFWbED6362XRFFPI5YyjfD2wRJd9yWLh/hn+6VyjcYA==", + "cpu": [ + "ia32" + ], + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/sass-embedded-android-riscv64": { + "version": "1.85.0", + "resolved": "https://registry.npmjs.org/sass-embedded-android-riscv64/-/sass-embedded-android-riscv64-1.85.0.tgz", + "integrity": "sha512-Fgkgay+5EePJXZFHR5Vlkutnsmox2V6nX4U3mfGbSN1xjLRm8F5ST72V2s5Z0mnIFpGvEu/v7hfptgViqMvaxg==", + "cpu": [ + "riscv64" + ], + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/sass-embedded-android-x64": { + "version": "1.85.0", + "resolved": "https://registry.npmjs.org/sass-embedded-android-x64/-/sass-embedded-android-x64-1.85.0.tgz", + "integrity": "sha512-/bG3JgTn3eoIDHCiJNVkLeJgUesat4ghxqYmKMZUJx++4e6iKCDj8XwQTJAgm+QDrsPKXHBacHEANJ9LEAuTqg==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "android" + ], + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/sass-embedded-darwin-arm64": { + "version": "1.85.0", + "resolved": "https://registry.npmjs.org/sass-embedded-darwin-arm64/-/sass-embedded-darwin-arm64-1.85.0.tgz", + "integrity": "sha512-plp8TyMz97YFBCB3ndftEvoW29vyfsSBJILM5U84cGzr06SvLh/Npjj8psfUeRw+upEk1zkFtw5u61sRCdgwIw==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "darwin" + ], + "engines": { + "node": ">=14.0.0" + } + }, "node_modules/sass-embedded-darwin-x64": { "version": "1.85.0", "resolved": "https://registry.npmjs.org/sass-embedded-darwin-x64/-/sass-embedded-darwin-x64-1.85.0.tgz", @@ -1074,7 +1152,214 @@ "os": [ "darwin" ], - "peer": true, + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/sass-embedded-linux-arm": { + "version": "1.85.0", + "resolved": "https://registry.npmjs.org/sass-embedded-linux-arm/-/sass-embedded-linux-arm-1.85.0.tgz", + "integrity": "sha512-18xOAEfazJt1MMVS2TRHV94n81VyMnywOoJ7/S7I79qno/zx26OoqqP4XvH107xu8+mZ9Gg54LrUH6ZcgHk08g==", + "cpu": [ + "arm" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/sass-embedded-linux-arm64": { + "version": "1.85.0", + "resolved": "https://registry.npmjs.org/sass-embedded-linux-arm64/-/sass-embedded-linux-arm64-1.85.0.tgz", + "integrity": "sha512-JRIRKVOY5Y8M1zlUOv9AQGju4P6lj8i5vLJZsVYVN/uY8Cd2dDJZPC8EOhjntp+IpF8AOGIHqCeCkHBceIyIjA==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/sass-embedded-linux-ia32": { + "version": "1.85.0", + "resolved": "https://registry.npmjs.org/sass-embedded-linux-ia32/-/sass-embedded-linux-ia32-1.85.0.tgz", + "integrity": "sha512-4JH+h+gLt9So22nNPQtsKojEsLzjld9ol3zWcOtMGclv+HojZGbCuhJUrLUcK72F8adXYsULmWhJPKROLIwYMA==", + "cpu": [ + "ia32" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/sass-embedded-linux-musl-arm": { + "version": "1.85.0", + "resolved": "https://registry.npmjs.org/sass-embedded-linux-musl-arm/-/sass-embedded-linux-musl-arm-1.85.0.tgz", + "integrity": "sha512-Z1j4ageDVFihqNUBnm89fxY46pY0zD/Clp1D3ZdI7S+D280+AEpbm5vMoH8LLhBQfQLf2w7H++SZGpQwrisudQ==", + "cpu": [ + "arm" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/sass-embedded-linux-musl-arm64": { + "version": "1.85.0", + "resolved": "https://registry.npmjs.org/sass-embedded-linux-musl-arm64/-/sass-embedded-linux-musl-arm64-1.85.0.tgz", + "integrity": "sha512-aoQjUjK28bvdw9XKTjQeayn8oWQ2QqvoTD11myklGd3IHH7Jj0nwXUstI4NxDueCKt3wghuZoIQkjOheReQxlg==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/sass-embedded-linux-musl-ia32": { + "version": "1.85.0", + "resolved": "https://registry.npmjs.org/sass-embedded-linux-musl-ia32/-/sass-embedded-linux-musl-ia32-1.85.0.tgz", + "integrity": "sha512-/cJCSXOfXmQFH8deE+3U9x+BSz8i0d1Tt9gKV/Gat1Xm43Oumw8pmZgno+cDuGjYQInr9ryW5121pTMlj/PBXQ==", + "cpu": [ + "ia32" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/sass-embedded-linux-musl-riscv64": { + "version": "1.85.0", + "resolved": "https://registry.npmjs.org/sass-embedded-linux-musl-riscv64/-/sass-embedded-linux-musl-riscv64-1.85.0.tgz", + "integrity": "sha512-l+FJxMXkmg42RZq5RFKXg4InX0IA7yEiPHe4kVSdrczP7z3NLxk+W9wVkPnoRKYIMe1qZPPQ25y0TgI4HNWouA==", + "cpu": [ + "riscv64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/sass-embedded-linux-musl-x64": { + "version": "1.85.0", + "resolved": "https://registry.npmjs.org/sass-embedded-linux-musl-x64/-/sass-embedded-linux-musl-x64-1.85.0.tgz", + "integrity": "sha512-M9ffjcYfFcRvkFA6V3DpOS955AyvmpvPAhL/xNK45d/ma1n1ehTWpd24tVeKiNK5CZkNjjMEfyw2fHa6MpqmEA==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/sass-embedded-linux-riscv64": { + "version": "1.85.0", + "resolved": "https://registry.npmjs.org/sass-embedded-linux-riscv64/-/sass-embedded-linux-riscv64-1.85.0.tgz", + "integrity": "sha512-yqPXQWfM+qiIPkfn++48GOlbmSvUZIyL9nwFstBk0k4x40UhbhilfknqeTUpxoHfQzylTGVhrm5JE7MjM+LNZA==", + "cpu": [ + "riscv64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/sass-embedded-linux-x64": { + "version": "1.85.0", + "resolved": "https://registry.npmjs.org/sass-embedded-linux-x64/-/sass-embedded-linux-x64-1.85.0.tgz", + "integrity": "sha512-NTDeQFZcuVR7COoaRy8pZD6/+QznwBR8kVFsj7NpmvX9aJ7TX/q+OQZHX7Bfb3tsfKXhf1YZozegPuYxRnMKAQ==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "linux" + ], + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/sass-embedded-win32-arm64": { + "version": "1.85.0", + "resolved": "https://registry.npmjs.org/sass-embedded-win32-arm64/-/sass-embedded-win32-arm64-1.85.0.tgz", + "integrity": "sha512-gO0VAuxC4AdV+uZYJESRWVVHQWCGzNs0C3OKCAdH4r1vGRugooMi7J/5wbwUdXDA1MV9ICfhlKsph2n3GiPdqA==", + "cpu": [ + "arm64" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/sass-embedded-win32-ia32": { + "version": "1.85.0", + "resolved": "https://registry.npmjs.org/sass-embedded-win32-ia32/-/sass-embedded-win32-ia32-1.85.0.tgz", + "integrity": "sha512-PCyn6xeFIBUgBceNypuf73/5DWF2VWPlPqPuBprPsTvpZOMUJeBtP+Lf4mnu3dNy1z76mYVnpaCnQmzZ0zHZaA==", + "cpu": [ + "ia32" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], + "engines": { + "node": ">=14.0.0" + } + }, + "node_modules/sass-embedded-win32-x64": { + "version": "1.85.0", + "resolved": "https://registry.npmjs.org/sass-embedded-win32-x64/-/sass-embedded-win32-x64-1.85.0.tgz", + "integrity": "sha512-AknE2jLp6OBwrR5hQ8pDsG94KhJCeSheFJ2xgbnk8RUjZX909JiNbgh2sNt9LG+RXf4xZa55dDL537gZoCx/iw==", + "cpu": [ + "x64" + ], + "license": "MIT", + "optional": true, + "os": [ + "win32" + ], "engines": { "node": ">=14.0.0" } @@ -1083,15 +1368,13 @@ "version": "0.25.0", "resolved": "https://registry.npmjs.org/scheduler/-/scheduler-0.25.0.tgz", "integrity": "sha512-xFVuu11jh+xcO7JOAGJNOXld8/TcEHK/4CituBUeUb5hqxJLj9YuemAEuvm9gQ/+pgXYfbQuqAkiYu+u7YEsNA==", - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/shallowequal": { "version": "1.1.0", "resolved": "https://registry.npmjs.org/shallowequal/-/shallowequal-1.1.0.tgz", "integrity": "sha512-y0m1JoUZSlPAjXVtPPW70aZWfIL/dSP7AFkRnniLCrK/8MDKog3TySTBmckD+RObVxH0v4Tox67+F14PdED2oQ==", - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/should": { "version": "13.2.3", @@ -1161,7 +1444,6 @@ "resolved": "https://registry.npmjs.org/source-map-js/-/source-map-js-1.2.1.tgz", "integrity": "sha512-UXWMKhLOwVKb728IUtQPXxfYU+usdybtUrK/8uGE8CQMvrhOpwvzDBwj0QhSL7MQc7vIsISBG8VQ8+IDQxpfQA==", "license": "BSD-3-Clause", - "peer": true, "engines": { "node": ">=0.10.0" } @@ -1208,7 +1490,6 @@ "resolved": "https://registry.npmjs.org/styled-components/-/styled-components-6.1.15.tgz", "integrity": "sha512-PpOTEztW87Ua2xbmLa7yssjNyUF9vE7wdldRfn1I2E6RTkqknkBYpj771OxM/xrvRGinLy2oysa7GOd7NcZZIA==", "license": "MIT", - "peer": true, "dependencies": { "@emotion/is-prop-valid": "1.2.2", "@emotion/unitless": "0.8.1", @@ -1236,22 +1517,19 @@ "version": "2.6.2", "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.6.2.tgz", "integrity": "sha512-AEYxH93jGFPn/a2iVAwW87VuUIkR1FVUKB77NwMF7nBTDkDrrT/Hpt/IrCJ0QXhW27jTBDcf5ZY7w6RiqTMw2Q==", - "license": "0BSD", - "peer": true + "license": "0BSD" }, "node_modules/stylis": { "version": "4.3.2", "resolved": "https://registry.npmjs.org/stylis/-/stylis-4.3.2.tgz", "integrity": "sha512-bhtUjWd/z6ltJiQwg0dUfxEJ+W+jdqQd8TbWLWyeIJHlnsqmGLRFFd8e5mA0AZi/zx90smXRlN66YMTcaSFifg==", - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/supports-color": { "version": "8.1.1", "resolved": "https://registry.npmjs.org/supports-color/-/supports-color-8.1.1.tgz", "integrity": "sha512-MpUEN2OodtUzxvKQl72cUF7RQ5EiHsGvSsVG0ia9c5RbWGL2CI4C7EpPS8UTBIplnlzZiNuV56w+FuNxy3ty2Q==", "license": "MIT", - "peer": true, "dependencies": { "has-flag": "^4.0.0" }, @@ -1294,7 +1572,6 @@ "resolved": "https://registry.npmjs.org/sync-child-process/-/sync-child-process-1.0.2.tgz", "integrity": "sha512-8lD+t2KrrScJ/7KXCSyfhT3/hRq78rC0wBFqNJXv3mZyn6hW2ypM05JmlSvtqRbeq6jqA94oHbxAr2vYsJ8vDA==", "license": "MIT", - "peer": true, "dependencies": { "sync-message-port": "^1.0.0" }, @@ -1307,7 +1584,6 @@ "resolved": "https://registry.npmjs.org/sync-message-port/-/sync-message-port-1.1.3.tgz", "integrity": "sha512-GTt8rSKje5FilG+wEdfCkOcLL7LWqpMlr2c3LRuKt/YXxcJ52aGSbGBAdI4L3aaqfrBt6y711El53ItyH1NWzg==", "license": "MIT", - "peer": true, "engines": { "node": ">=16.0.0" } @@ -1322,8 +1598,7 @@ "version": "2.8.1", "resolved": "https://registry.npmjs.org/tslib/-/tslib-2.8.1.tgz", "integrity": "sha512-oJFu94HQb+KVduSUQL7wnpmqnfmLsOA/nAh6b6EH0wCEoK0/mPeXU6c3wKDV83MkOuHPRHtSXKKU99IBazS/2w==", - "license": "0BSD", - "peer": true + "license": "0BSD" }, "node_modules/uri-js-replace": { "version": "1.0.1", @@ -1350,8 +1625,7 @@ "version": "6.0.0", "resolved": "https://registry.npmjs.org/varint/-/varint-6.0.0.tgz", "integrity": "sha512-cXEIW6cfr15lFv563k4GuVuW/fiwjknytD37jIOLSdSWuOI6WnO/oKwmP2FQTU2l01LP8/M5TSAJpzUaGe3uWg==", - "license": "MIT", - "peer": true + "license": "MIT" }, "node_modules/webidl-conversions": { "version": "3.0.1", diff --git a/static/images/habitat/authorize.png b/static/images/habitat/authorize.png new file mode 100644 index 0000000000..e06f071ccf Binary files /dev/null and b/static/images/habitat/authorize.png differ diff --git a/static/images/habitat/builder_sign_in.png b/static/images/habitat/builder_sign_in.png new file mode 100644 index 0000000000..66b1e9fd2f Binary files /dev/null and b/static/images/habitat/builder_sign_in.png differ