diff --git a/_data/docs.yml b/_data/docs.yml index 43d53d2..fa2f2bd 100644 --- a/_data/docs.yml +++ b/_data/docs.yml @@ -11,6 +11,8 @@ url: /docs/configuration/accessories/ - title: "Aliases" url: /docs/configuration/aliases/ + - title: "Anchors" + url: /docs/configuration/anchors/ - title: "Booting" url: /docs/configuration/booting/ - title: "Builders" diff --git a/docs/configuration/anchors.md b/docs/configuration/anchors.md new file mode 100644 index 0000000..3c48f6e --- /dev/null +++ b/docs/configuration/anchors.md @@ -0,0 +1,30 @@ +--- +title: Anchors +--- + +# Anchors + +You can re-use parts of your Kamal configuration by defining them as anchors and referencing them with aliases. + +For example, you might need to define a shared healthcheck for multiple worker roles. Anchors +begin with `x-` and are defined at the root level of your deploy.yml file. + +```yaml +x-worker-healthcheck: &worker-healthcheck + health-cmd: bin/worker-healthcheck + health-start-period: 5s + health-retries: 5 + health-interval: 5s +``` + +To use this anchor in your deploy configuration, reference it via the alias. + +```yaml +servers: + worker: + hosts: + - 867.53.0.9 + cmd: bin/jobs + options: + <<: *worker-healthcheck +``` diff --git a/docs/configuration/overview.md b/docs/configuration/overview.md index 8fe00b9..72afed4 100644 --- a/docs/configuration/overview.md +++ b/docs/configuration/overview.md @@ -16,7 +16,7 @@ e.g., `kamal deploy -d staging`. In this case, the configuration will also be read from `config/deploy.staging.yml` and merged with the base configuration. -## [Extensions](#extensions) +## [Anchors](#anchors) Kamal will not accept unrecognized keys in the configuration file. @@ -24,7 +24,7 @@ However, you might want to declare a configuration block using YAML anchors and aliases to avoid repetition. You can prefix a configuration section with `x-` to indicate that it is an -extension. Kamal will ignore the extension and not raise an error. +anchor. Kamal will ignore the anchor and not raise an error. See [Anchors](../anchors) for more information. ## [The service name](#the-service-name)