diff --git a/.github/workflows/check-legacy-links-format.yml b/.github/workflows/check-legacy-links-format.yml new file mode 100644 index 0000000000..f067bd231a --- /dev/null +++ b/.github/workflows/check-legacy-links-format.yml @@ -0,0 +1,17 @@ +name: Legacy Link Format Checker + +on: + push: + paths: + - "website/content/**/*.mdx" + - "website/data/*-nav-data.json" + +jobs: + check-links: + uses: hashicorp/dev-portal/.github/workflows/docs-content-check-legacy-links-format.yml@475289345d312552b745224b46895f51cc5fc490 + with: + repo-owner: "hashicorp" + repo-name: "consul" + commit-sha: ${{ github.sha }} + mdx-directory: "website/content" + nav-data-directory: "website/data" diff --git a/.github/workflows/test-link-rewrites.yml b/.github/workflows/test-link-rewrites.yml new file mode 100644 index 0000000000..b189c6d79c --- /dev/null +++ b/.github/workflows/test-link-rewrites.yml @@ -0,0 +1,16 @@ +name: Test Link Rewrites + +on: [deployment_status] + +jobs: + test-link-rewrites: + if: github.event.deployment_status.state == 'success' + uses: hashicorp/dev-portal/.github/workflows/docs-content-link-rewrites-e2e.yml@2aceb60125f6c15f4c8dbe2e4d79148047bfa437 + with: + repo-owner: "hashicorp" + repo-name: "consul" + commit-sha: ${{ github.sha }} + main-branch-preview-url: "https://consul-git-main-hashicorp.vercel.app/" + # Workflow is only intended to run for one single migration PR + # This variable does not need to be updated + pr-branch-preview-url: "https://consul-git-docs-ambmigrate-link-formats-hashicorp.vercel.app/" diff --git a/website/content/api-docs/acl/auth-methods.mdx b/website/content/api-docs/acl/auth-methods.mdx index f40ad2575c..7b65bf6903 100644 --- a/website/content/api-docs/acl/auth-methods.mdx +++ b/website/content/api-docs/acl/auth-methods.mdx @@ -14,7 +14,7 @@ The `/acl/auth-method` endpoints [create](#create-an-auth-method), ACL auth methods in Consul. For more information on how to setup ACLs, please check -the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production). +the [ACL tutorial](/consul/tutorials/security/access-control-setup-production). ## Create an Auth Method @@ -25,16 +25,16 @@ This endpoint creates a new ACL auth method. | `PUT` | `/acl/auth-method` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `acl:write` | -The corresponding CLI command is [`consul acl auth-method create`](/commands/acl/auth-method/create). +The corresponding CLI command is [`consul acl auth-method create`](/consul/commands/acl/auth-method/create). ### Query Parameters @@ -49,7 +49,7 @@ The corresponding CLI command is [`consul acl auth-method create`](/commands/acl - `Type` `(string: )` - The type of auth method being configured. This field is immutable. For allowed values see the [auth method - documentation](/docs/security/acl/auth-methods). + documentation](/consul/docs/security/acl/auth-methods). - `Description` `(string: "")` - Free form human readable description of the auth method. @@ -59,7 +59,7 @@ The corresponding CLI command is [`consul acl auth-method create`](/commands/acl - `MaxTokenTTL` `(duration: 0s)` - This specifies the maximum life of any token created by this auth method. When set it will initialize the - [`ExpirationTime`](/api-docs/acl/tokens#expirationtime) field on all tokens + [`ExpirationTime`](/consul/api-docs/acl/tokens#expirationtime) field on all tokens to a value of `Token.CreateTime + AuthMethod.MaxTokenTTL`. This field is not persisted beyond its initial use. Can be specified in the form of `"60s"` or `"5m"` (i.e., 60 seconds or 5 minutes, respectively). This value must be no @@ -74,7 +74,7 @@ The corresponding CLI command is [`consul acl auth-method create`](/commands/acl - `Config` `(map[string]string: )` - The raw configuration to use for the chosen auth method. Contents will vary depending upon the type chosen. For more information on configuring specific auth method types, see the [auth - method documentation](/docs/security/acl/auth-methods). + method documentation](/consul/docs/security/acl/auth-methods). - `Namespace` `(string: "")` - Specifies the namespace of the auth method you create. This field takes precedence over the `ns` query parameter, @@ -156,16 +156,16 @@ auth method exists with the given name, a 404 is returned instead of a | `GET` | `/acl/auth-method/:name` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `YES` | `all` | `none` | `acl:read` | -The corresponding CLI command is [`consul acl auth-method read`](/commands/acl/auth-method/read). +The corresponding CLI command is [`consul acl auth-method read`](/consul/commands/acl/auth-method/read). ### Path Parameters @@ -208,16 +208,16 @@ This endpoint updates an existing ACL auth method. | `PUT` | `/acl/auth-method/:name` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `acl:write` | -The corresponding CLI command is [`consul acl auth-method update`](/commands/acl/auth-method/update). +The corresponding CLI command is [`consul acl auth-method update`](/consul/commands/acl/auth-method/update). ### Path Parameters @@ -246,7 +246,7 @@ The corresponding CLI command is [`consul acl auth-method update`](/commands/acl - `MaxTokenTTL` `(duration: 0s)` - This specifies the maximum life of any token created by this auth method. When set it will initialize the - [`ExpirationTime`](/api-docs/acl/tokens#expirationtime) field on all tokens + [`ExpirationTime`](/consul/api-docs/acl/tokens#expirationtime) field on all tokens to a value of `Token.CreateTime + AuthMethod.MaxTokenTTL`. This field is not persisted beyond its initial use. Can be specified in the form of `"60s"` or `"5m"` (i.e., 60 seconds or 5 minutes, respectively). This value must be no @@ -261,7 +261,7 @@ The corresponding CLI command is [`consul acl auth-method update`](/commands/acl - `Config` `(map[string]string: )` - The raw configuration to use for the chosen auth method. Contents will vary depending upon the type chosen. For more information on configuring specific auth method types, see the [auth - method documentation](/docs/security/acl/auth-methods). + method documentation](/consul/docs/security/acl/auth-methods). - `Namespace` `(string: "")` - Specifies the namespace of the auth method you update. This field takes precedence over the `ns` query parameter, @@ -336,8 +336,8 @@ $ curl --request PUT \ This endpoint deletes an ACL auth method. ~> Deleting an auth method will also immediately delete all associated -[binding rules](/api-docs/acl/binding-rules) as well as any -outstanding [tokens](/api-docs/acl/tokens) created from this auth method. +[binding rules](/consul/api-docs/acl/binding-rules) as well as any +outstanding [tokens](/consul/api-docs/acl/tokens) created from this auth method. | Method | Path | Produces | | -------- | ------------------------ | ------------------ | @@ -347,16 +347,16 @@ Even though the return type is application/json, the value is either true or false indicating whether the delete succeeded. The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `acl:write` | -The corresponding CLI command is [`consul acl auth-method delete`](/commands/acl/auth-method/delete). +The corresponding CLI command is [`consul acl auth-method delete`](/consul/commands/acl/auth-method/delete). ### Path Parameters @@ -389,16 +389,16 @@ This endpoint lists all the ACL auth methods. | `GET` | `/acl/auth-methods` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `YES` | `all` | `none` | `acl:read` | -The corresponding CLI command is [`consul acl auth-method list`](/commands/acl/auth-method/list). +The corresponding CLI command is [`consul acl auth-method list`](/consul/commands/acl/auth-method/list). ### Query Parameters diff --git a/website/content/api-docs/acl/binding-rules.mdx b/website/content/api-docs/acl/binding-rules.mdx index 893dc485f9..043086f58a 100644 --- a/website/content/api-docs/acl/binding-rules.mdx +++ b/website/content/api-docs/acl/binding-rules.mdx @@ -14,7 +14,7 @@ The `/acl/binding-rule` endpoints [create](#create-a-binding-rule), rules in Consul. For more information on how to setup ACLs, please check -the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production). +the [ACL tutorial](/consul/tutorials/security/access-control-setup-production). ## Create a Binding Rule @@ -25,16 +25,16 @@ This endpoint creates a new ACL binding rule. | `PUT` | `/acl/binding-rule` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `acl:write` | -The corresponding CLI command is [`consul acl binding-rule create`](/commands/acl/binding-rule/create). +The corresponding CLI command is [`consul acl binding-rule create`](/consul/commands/acl/binding-rule/create). ### Query Parameters @@ -154,16 +154,16 @@ response. | `GET` | `/acl/binding-rule/:id` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `YES` | `all` | `none` | `acl:read` | -The corresponding CLI command is [`consul acl binding-rule read`](/commands/acl/binding-rule/read). +The corresponding CLI command is [`consul acl binding-rule read`](/consul/commands/acl/binding-rule/read). ### Path Parameters @@ -204,16 +204,16 @@ This endpoint updates an existing ACL binding rule. | `PUT` | `/acl/binding-rule/:id` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `acl:write` | -The corresponding CLI command is [`consul acl binding-rule update`](/commands/acl/binding-rule/update). +The corresponding CLI command is [`consul acl binding-rule update`](/consul/commands/acl/binding-rule/update). ### Path Parameters @@ -342,16 +342,16 @@ Even though the return type is application/json, the value is either true or false indicating whether the delete succeeded. The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `acl:write` | -The corresponding CLI command is [`consul acl binding-rule delete`](/commands/acl/binding-rule/delete). +The corresponding CLI command is [`consul acl binding-rule delete`](/consul/commands/acl/binding-rule/delete). ### Path Parameters @@ -384,16 +384,16 @@ This endpoint lists all the ACL binding rules. | `GET` | `/acl/binding-rules` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `YES` | `all` | `none` | `acl:read` | -The corresponding CLI command is [`consul acl binding-rule list`](/commands/acl/binding-rule/list). +The corresponding CLI command is [`consul acl binding-rule list`](/consul/commands/acl/binding-rule/list). ## Query Parameters diff --git a/website/content/api-docs/acl/index.mdx b/website/content/api-docs/acl/index.mdx index 0e5393a7fd..0eeb7c7222 100644 --- a/website/content/api-docs/acl/index.mdx +++ b/website/content/api-docs/acl/index.mdx @@ -6,17 +6,17 @@ description: The /acl endpoints manage the Consul's ACL system. # ACL HTTP API --> **1.4.0+:** This API documentation is for Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api-docs/acl/legacy). +-> **1.4.0+:** This API documentation is for Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/consul/api-docs/acl/legacy). -The `/acl` endpoints are used to manage ACL tokens and policies in Consul, [bootstrap the ACL system](#bootstrap-acls), [check ACL replication status](#check-acl-replication), and [translate rules](#translate-rules). There are additional pages for managing [tokens](/api-docs/acl/tokens) and [policies](/api-docs/acl/policies) with the `/acl` endpoints. +The `/acl` endpoints are used to manage ACL tokens and policies in Consul, [bootstrap the ACL system](#bootstrap-acls), [check ACL replication status](#check-acl-replication), and [translate rules](#translate-rules). There are additional pages for managing [tokens](/consul/api-docs/acl/tokens) and [policies](/consul/api-docs/acl/policies) with the `/acl` endpoints. For more information on how to setup ACLs, please check -the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production). +the [ACL tutorial](/consul/tutorials/security/access-control-setup-production). ## Bootstrap ACLs This endpoint does a special one-time bootstrap of the ACL system, making the first -management token if the [`acl.tokens.initial_management`](/docs/agent/config/config-files#acl_tokens_initial_management) +management token if the [`acl.tokens.initial_management`](/consul/docs/agent/config/config-files#acl_tokens_initial_management) configuration entry is not specified in the Consul server configuration and if the cluster has not been bootstrapped previously. An operator created token can be provided in the body of the request to bootstrap the cluster if required. The provided token should be presented in a UUID format. @@ -29,16 +29,16 @@ configuration files. | `PUT` | `/acl/bootstrap` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `none` | -The corresponding CLI command is [`consul acl bootstrap`](/commands/acl/bootstrap). +The corresponding CLI command is [`consul acl bootstrap`](/consul/commands/acl/bootstrap). ### Sample Request @@ -97,7 +97,7 @@ consider the cluster in a potentially compromised state. The returned token will have unrestricted privileges to manage all details of the system. It can then be used to further configure the ACL system. Please check the -[ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) for more details. +[ACL tutorial](/consul/tutorials/security/access-control-setup-production) for more details. ## Check ACL Replication @@ -105,7 +105,7 @@ This endpoint returns the status of the ACL replication processes in the datacenter. This is intended to be used by operators or by automation checking to discover the health of ACL replication. -Please check the [ACL Replication tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-replication-multiple-datacenters) +Please check the [ACL Replication tutorial](/consul/tutorials/security-operations/access-control-replication-multiple-datacenters) for more details. | Method | Path | Produces | @@ -113,10 +113,10 @@ for more details. | `GET` | `/acl/replication` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | @@ -159,7 +159,7 @@ $ curl \ - `SourceDatacenter` - The authoritative ACL datacenter that ACLs are being replicated from and will match the - [`primary_datacenter`](/docs/agent/config/config-files#primary_datacenter) configuration. + [`primary_datacenter`](/consul/docs/agent/config/config-files#primary_datacenter) configuration. - `ReplicationType` - The type of replication that is currently in use. @@ -173,17 +173,17 @@ $ curl \ - `ReplicatedIndex` - The last index that was successfully replicated. Which data the replicated index refers to depends on the replication type. For `legacy` replication this can be compared with the value of the `X-Consul-Index` header - returned by the [`/v1/acl/list`](/api-docs/acl/legacy#list-acls) endpoint to + returned by the [`/v1/acl/list`](/consul/api-docs/acl/legacy#list-acls) endpoint to determine if the replication process has gotten all available ACLs. When in either `tokens` or `policies` mode, this index can be compared with the value of the - `X-Consul-Index` header returned by the [`/v1/acl/policies`](/api-docs/acl/policies#list-policies) + `X-Consul-Index` header returned by the [`/v1/acl/policies`](/consul/api-docs/acl/policies#list-policies) endpoint to determine if the policy replication process has gotten all available ACL policies. Note that ACL replication is rate limited so the indexes may lag behind the primary datacenter. - `ReplicatedTokenIndex` - The last token index that was successfully replicated. This index can be compared with the value of the `X-Consul-Index` header returned - by the [`/v1/acl/tokens`](/api-docs/acl/tokens#list-tokens) endpoint to determine + by the [`/v1/acl/tokens`](/consul/api-docs/acl/tokens#list-tokens) endpoint to determine if the replication process has gotten all available ACL tokens. Note that ACL replication is rate limited so the indexes may lag behind the primary datacenter. @@ -215,16 +215,16 @@ migrations. | `POST` | `/acl/rules/translate` | `text/plain` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `acl:read` | -The corresponding CLI command is [`consul acl translate-rules`](/commands/acl/translate-rules). +The corresponding CLI command is [`consul acl translate-rules`](/consul/commands/acl/translate-rules). ### Sample Payload @@ -257,23 +257,23 @@ This endpoint translates the legacy rules embedded within a legacy ACL into the syntax. It is intended to be used by operators managing Consul's ACLs and performing legacy token to new policy migrations. Note that this API requires the auto-generated Accessor ID of the legacy token. This ID can be retrieved using the -[`/v1/acl/token/self`](/api-docs/acl/tokens#read-self-token) endpoint. +[`/v1/acl/token/self`](/consul/api-docs/acl/tokens#read-self-token) endpoint. | Method | Path | Produces | | ------ | ----------------------------------- | ------------ | | `GET` | `/acl/rules/translate/:accessor_id` | `text/plain` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `acl:read` | -The corresponding CLI command is [`consul acl translate-rules`](/commands/acl/translate-rules). +The corresponding CLI command is [`consul acl translate-rules`](/consul/commands/acl/translate-rules). ### Sample Request @@ -292,7 +292,7 @@ agent_prefix "" { ## Login to Auth Method This endpoint was added in Consul 1.5.0 and is used to exchange an [auth -method](/docs/security/acl/auth-methods) bearer token for a newly-created +method](/consul/docs/security/acl/auth-methods) bearer token for a newly-created Consul ACL token. | Method | Path | Produces | @@ -300,10 +300,10 @@ Consul ACL token. | `POST` | `/acl/login` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | @@ -311,12 +311,12 @@ The table below shows this endpoint's support for -> **Note** - To use the login process to create tokens in any connected secondary datacenter, [ACL -replication](/docs/agent/config/config-files#acl_enable_token_replication) must be +replication](/consul/docs/agent/config/config-files#acl_enable_token_replication) must be enabled. Login requires the ability to create local tokens which is restricted to the primary datacenter and any secondary datacenters with ACL token replication enabled. -The corresponding CLI command is [`consul login`](/commands/login). +The corresponding CLI command is [`consul login`](/consul/commands/login). ### Query Parameters @@ -395,10 +395,10 @@ with the `X-Consul-Token` header or the `token` query parameter. | `POST` | `/acl/logout` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | @@ -407,7 +407,7 @@ The table below shows this endpoint's support for -> **Note** - This endpoint requires no specific privileges as it is just deleting a token for which you already must possess its secret. -The corresponding CLI command is [`consul logout`](/commands/logout). +The corresponding CLI command is [`consul logout`](/consul/commands/logout). ### Sample Request @@ -426,17 +426,17 @@ $ curl \ This endpoint was added in Consul 1.8.0 and is used to obtain an authorization -URL from Consul to start an [OIDC login flow](/docs/security/acl/auth-methods/oidc). +URL from Consul to start an [OIDC login flow](/consul/docs/security/acl/auth-methods/oidc). | Method | Path | Produces | | ------ | -------------------- | ------------------ | | `POST` | `/acl/oidc/auth-url` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | @@ -444,7 +444,7 @@ The table below shows this endpoint's support for -> **Note** - To use the login process to create tokens in any connected secondary datacenter, [ACL -replication](/docs/agent/config/config-files#acl_enable_token_replication) must be +replication](/consul/docs/agent/config/config-files#acl_enable_token_replication) must be enabled. Login requires the ability to create local tokens which is restricted to the primary datacenter and any secondary datacenters with ACL token replication enabled. @@ -457,10 +457,10 @@ replication enabled. ### JSON Request Body Schema - `AuthMethod` `(string: )` - The name of the auth method to use for - login. This must be of type [`oidc`](/docs/security/acl/auth-methods/oidc). + login. This must be of type [`oidc`](/consul/docs/security/acl/auth-methods/oidc). - `RedirectURI` `(string: )` - See [Redirect - URIs](/docs/security/acl/auth-methods/oidc#redirect-uris) for more information. + URIs](/consul/docs/security/acl/auth-methods/oidc#redirect-uris) for more information. - `ClientNonce` `(string: "")` - Optional client-provided nonce that must match during callback, if present. @@ -516,10 +516,10 @@ for a newly-created Consul ACL token. | `POST` | `/acl/oidc/callback` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | @@ -527,7 +527,7 @@ The table below shows this endpoint's support for -> **Note** - To use the login process to create tokens in any connected secondary datacenter, [ACL -replication](/docs/agent/config/config-files#acl_enable_token_replication) must be +replication](/consul/docs/agent/config/config-files#acl_enable_token_replication) must be enabled. Login requires the ability to create local tokens which is restricted to the primary datacenter and any secondary datacenters with ACL token replication enabled. @@ -540,7 +540,7 @@ replication enabled. ### JSON Request Body Schema - `AuthMethod` `(string: )` - The name of the auth method to use for - login. This must be of type [`oidc`](/docs/security/acl/auth-methods/oidc). + login. This must be of type [`oidc`](/consul/docs/security/acl/auth-methods/oidc). - `State` `(string: )` - Opaque state ID that is part of the Authorization URL and will be included in the the redirect following diff --git a/website/content/api-docs/acl/legacy.mdx b/website/content/api-docs/acl/legacy.mdx index da8144157f..3dd88d57fd 100644 --- a/website/content/api-docs/acl/legacy.mdx +++ b/website/content/api-docs/acl/legacy.mdx @@ -10,11 +10,11 @@ description: >- -> **The legacy ACL system was deprecated in Consul 1.4.0 and removed in Consul 1.11.0.** It's _strongly_ recommended you do not build anything using the legacy system and use -the new ACL [Token](/api-docs/acl/tokens) and [Policy](/api-docs/acl/policies) APIs instead. +the new ACL [Token](/consul/api-docs/acl/tokens) and [Policy](/consul/api-docs/acl/policies) APIs instead. The legacy `/acl` endpoints to create, update, destroy, and query legacy ACL tokens in Consul. -For more information about ACLs, please check the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production). +For more information about ACLs, please check the [ACL tutorial](/consul/tutorials/security/access-control-setup-production). ## Create ACL Token @@ -25,10 +25,10 @@ This endpoint makes a new ACL token. | `PUT` | `/acl/create` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | @@ -45,7 +45,7 @@ The table below shows this endpoint's support for are: `client` and `management`. - `Rules` `(string: "")` - Specifies rules for this ACL token. The format of the - `Rules` property is detailed in the [ACL Rule documentation](/docs/security/acl/acl-rules). + `Rules` property is detailed in the [ACL Rule documentation](/consul/docs/security/acl/acl-rules). ### Sample Payload @@ -84,10 +84,10 @@ generating a new token ID, the `ID` field must be provided. | `PUT` | `/acl/update` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | @@ -138,10 +138,10 @@ Even though the return type is application/json, the value is either true or false, indicating whether the delete succeeded. The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | @@ -175,10 +175,10 @@ This endpoint reads an ACL token with the given ID. | `GET` | `/acl/info/:uuid` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | @@ -224,10 +224,10 @@ complex rule management. | `PUT` | `/acl/clone/:uuid` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | @@ -263,10 +263,10 @@ This endpoint lists all the active ACL tokens. | `GET` | `/acl/list` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | @@ -296,4 +296,4 @@ $ curl \ ## Check ACL Replication -The check ACL replication endpoint has not changed between the legacy system and the new system. Review the [latest documentation](/api-docs/acl#check-acl-replication) to learn more about this endpoint. +The check ACL replication endpoint has not changed between the legacy system and the new system. Review the [latest documentation](/consul/api-docs/acl#check-acl-replication) to learn more about this endpoint. diff --git a/website/content/api-docs/acl/policies.mdx b/website/content/api-docs/acl/policies.mdx index 4668bc3c86..e4fb09de0f 100644 --- a/website/content/api-docs/acl/policies.mdx +++ b/website/content/api-docs/acl/policies.mdx @@ -6,14 +6,14 @@ description: The /acl/policy endpoints manage Consul's ACL policies. # ACL Policy HTTP API --> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api-docs/acl/legacy). +-> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/consul/api-docs/acl/legacy). The `/acl/policy` endpoints [create](#create-a-policy), [read](#read-a-policy), [update](#update-a-policy), [list](#list-policies) and [delete](#delete-a-policy) ACL policies in Consul. For more information on how to setup ACLs, please check -the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production). +the [ACL tutorial](/consul/tutorials/security/access-control-setup-production). ## Create a Policy @@ -24,16 +24,16 @@ This endpoint creates a new ACL policy. | `PUT` | `/acl/policy` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `acl:write` | -The corresponding CLI command is [`consul acl policy create`](/commands/acl/policy/create). +The corresponding CLI command is [`consul acl policy create`](/consul/commands/acl/policy/create). ### Query Parameters @@ -49,7 +49,7 @@ The corresponding CLI command is [`consul acl policy create`](/commands/acl/poli - `Description` `(string: "")` - Free form human readable description of the policy. - `Rules` `(string: "")` - Specifies rules for the ACL policy. The format of the - `Rules` property is detailed in the [ACL Rules documentation](/docs/security/acl/acl-rules). + `Rules` property is detailed in the [ACL Rules documentation](/consul/docs/security/acl/acl-rules). - `Datacenters` `(array)` - Specifies the datacenters the policy is valid within. When no datacenters are provided the policy is valid in all datacenters including @@ -102,16 +102,16 @@ This endpoint reads an ACL policy with the given ID. | `GET` | `/acl/policy/:id` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `YES` | `all` | `none` | `acl:read` | -The corresponding CLI command is [`consul acl policy read`](/commands/acl/policy/read). +The corresponding CLI command is [`consul acl policy read`](/consul/commands/acl/policy/read). ### Path Parameters @@ -152,16 +152,16 @@ This endpoint reads an ACL policy with the given ID. | `GET` | `/acl/policy/name/:name` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `YES` | `all` | `none` | `acl:read` | -The corresponding CLI command is [`consul acl policy read -name=`](/commands/acl/policy/read#name). +The corresponding CLI command is [`consul acl policy read -name=`](/consul/commands/acl/policy/read#name). ### Path Parameters @@ -202,16 +202,16 @@ This endpoint updates an existing ACL policy. | `PUT` | `/acl/policy/:id` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `acl:write` | -The corresponding CLI command is [`consul acl policy update`](/commands/acl/policy/update). +The corresponding CLI command is [`consul acl policy update`](/consul/commands/acl/policy/update). ### Path Parameters @@ -234,7 +234,7 @@ The corresponding CLI command is [`consul acl policy update`](/commands/acl/poli - `Description` `(string: "")` - Free form human readable description of this policy. - `Rules` `(string: "")` - Specifies rules for this ACL policy. The format of the - `Rules` property is detailed in the [ACL Rules documentation](/docs/security/acl/acl-rules). + `Rules` property is detailed in the [ACL Rules documentation](/consul/docs/security/acl/acl-rules). - `Datacenters` `(array)` - Specifies the datacenters this policy is valid within. When no datacenters are provided the policy is valid in all datacenters including @@ -289,16 +289,16 @@ Even though the return type is application/json, the value is either true or false indicating whether the delete succeeded. The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `acl:write` | -The corresponding CLI command is [`consul acl policy delete`](/commands/acl/policy/delete). +The corresponding CLI command is [`consul acl policy delete`](/consul/commands/acl/policy/delete). ### Path Parameters @@ -331,16 +331,16 @@ This endpoint lists all the ACL policies. | `GET` | `/acl/policies` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `YES` | `all` | `none` | `acl:read` | -The corresponding CLI command is [`consul acl policy list`](/commands/acl/policy/list). +The corresponding CLI command is [`consul acl policy list`](/consul/commands/acl/policy/list). ### Query Parameters diff --git a/website/content/api-docs/acl/roles.mdx b/website/content/api-docs/acl/roles.mdx index 9648670720..3da27002d4 100644 --- a/website/content/api-docs/acl/roles.mdx +++ b/website/content/api-docs/acl/roles.mdx @@ -12,7 +12,7 @@ The `/acl/role` endpoints [create](#create-a-role), [read](#read-a-role), [update](#update-a-role), [list](#list-roles) and [delete](#delete-a-role) ACL roles in Consul. For more information on how to setup ACLs, please check -the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production). +the [ACL tutorial](/consul/tutorials/security/access-control-setup-production). ## Create a Role @@ -23,16 +23,16 @@ This endpoint creates a new ACL role. | `PUT` | `/acl/role` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `acl:write` | -The corresponding CLI command is [`consul acl role create`](/commands/acl/role/create). +The corresponding CLI command is [`consul acl role create`](/consul/commands/acl/role/create). ### Query Parameters @@ -56,7 +56,7 @@ The corresponding CLI command is [`consul acl role create`](/commands/acl/role/c breaking tokens. - `ServiceIdentities` `(array)` - The list of [service - identities](/docs/security/acl#service-identities) that should be + identities](/consul/docs/security/acl#service-identities) that should be applied to the role. Added in Consul 1.5.0. - `ServiceName` `(string: )` - The name of the service. The name @@ -70,7 +70,7 @@ The corresponding CLI command is [`consul acl role create`](/commands/acl/role/c but may in the future. - `NodeIdentities` `(array)` - The list of [node - identities](/docs/security/acl#node-identities) that should be + identities](/consul/docs/security/acl#node-identities) that should be applied to the role. Added in Consul 1.8.1. - `NodeName` `(string: )` - The name of the node. The name @@ -169,16 +169,16 @@ given ID, a 404 is returned instead of a 200 response. | `GET` | `/acl/role/:id` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `YES` | `all` | `none` | `acl:read` | -The corresponding CLI command is [`consul acl role read`](/commands/acl/role/read). +The corresponding CLI command is [`consul acl role read`](/consul/commands/acl/role/read). ### Path Parameters @@ -239,16 +239,16 @@ given name, a 404 is returned instead of a 200 response. | `GET` | `/acl/role/name/:name` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `YES` | `all` | `none` | `acl:read` | -The corresponding CLI command is [`consul acl role read -name=`](/commands/acl/role/read#name). +The corresponding CLI command is [`consul acl role read -name=`](/consul/commands/acl/role/read#name). ### Path Parameters @@ -308,16 +308,16 @@ This endpoint updates an existing ACL role. | `PUT` | `/acl/role/:id` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `acl:write` | -The corresponding CLI command is [`consul acl role update`](/commands/acl/role/update). +The corresponding CLI command is [`consul acl role update`](/consul/commands/acl/role/update). ### Path Parameters @@ -347,11 +347,11 @@ The corresponding CLI command is [`consul acl role update`](/commands/acl/role/u breaking tokens. - `ServiceIdentities` `(array)` - The list of [service - identities](/docs/security/acl#service-identities) that should be + identities](/consul/docs/security/acl#service-identities) that should be applied to the role. Added in Consul 1.5.0. - `NodeIdentities` `(array)` - The list of [node - identities](/docs/security/acl#node-identities) that should be + identities](/consul/docs/security/acl#node-identities) that should be applied to the role. Added in Consul 1.8.1. - `Namespace` `(string: "")` - Specifies the namespace of the role you update. @@ -432,16 +432,16 @@ Even though the return type is application/json, the value is either true or false indicating whether the delete succeeded. The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `acl:write` | -The corresponding CLI command is [`consul acl role delete`](/commands/acl/role/delete). +The corresponding CLI command is [`consul acl role delete`](/consul/commands/acl/role/delete). ### Path Parameters @@ -474,16 +474,16 @@ This endpoint lists all the ACL roles. | `GET` | `/acl/roles` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `YES` | `all` | `none` | `acl:read` | -The corresponding CLI command is [`consul acl role list`](/commands/acl/role/list). +The corresponding CLI command is [`consul acl role list`](/consul/commands/acl/role/list). ### Query Parameters diff --git a/website/content/api-docs/acl/tokens.mdx b/website/content/api-docs/acl/tokens.mdx index b6f6c2d7c4..87819fc620 100644 --- a/website/content/api-docs/acl/tokens.mdx +++ b/website/content/api-docs/acl/tokens.mdx @@ -6,13 +6,13 @@ description: The /acl/token endpoints manage Consul's ACL Tokens. # ACL Token HTTP API --> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/api-docs/acl/legacy). +-> **1.4.0+:** The APIs are available in Consul versions 1.4.0 and later. The documentation for the legacy ACL API is [here](/consul/api-docs/acl/legacy). The `/acl/token` endpoints [create](#create-a-token), [read](#read-a-token), [update](#update-a-token), [list](#list-tokens), [clone](#clone-a-token) and [delete](#delete-a-token) ACL tokens in Consul. For more information on how to setup ACLs, please check -the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production). +the [ACL tutorial](/consul/tutorials/security/access-control-setup-production). ## Create a Token @@ -23,16 +23,16 @@ This endpoint creates a new ACL token. | `PUT` | `/acl/token` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `acl:write` | -The corresponding CLI command is [`consul acl token create`](/commands/acl/token/create). +The corresponding CLI command is [`consul acl token create`](/consul/commands/acl/token/create). ### Query Parameters @@ -67,7 +67,7 @@ The corresponding CLI command is [`consul acl token create`](/commands/acl/token enables role renaming without breaking tokens. Added in Consul 1.5.0. - `ServiceIdentities` `(array)` - The list of [service - identities](/docs/security/acl#service-identities) that should be + identities](/consul/docs/security/acl#service-identities) that should be applied to the token. Added in Consul 1.5.0. - `ServiceName` `(string: )` - The name of the service. The name @@ -81,7 +81,7 @@ The corresponding CLI command is [`consul acl token create`](/commands/acl/token but may in the future. - `NodeIdentities` `(array)` - The list of [node - identities](/docs/security/acl#node-identities) that should be + identities](/consul/docs/security/acl#node-identities) that should be applied to the token. Added in Consul 1.8.1. - `NodeName` `(string: )` - The name of the node. The name @@ -169,16 +169,16 @@ This endpoint reads an ACL token with the given Accessor ID. | `GET` | `/acl/token/:AccessorID` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `YES` | `all` | `none` | `acl:read` | -The corresponding CLI command is [`consul acl token read`](/commands/acl/token/read). +The corresponding CLI command is [`consul acl token read`](/consul/commands/acl/token/read). ### Path Parameters @@ -325,10 +325,10 @@ specified with the `X-Consul-Token` header or the `token` query parameter. | `GET` | `/acl/token/self` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | @@ -337,7 +337,7 @@ The table below shows this endpoint's support for -> **Note** - This endpoint requires no specific privileges as it is just retrieving the data for a token that you must already possess its secret. -The corresponding CLI command is [`consul acl token read -self`](/commands/acl/token/read#self). +The corresponding CLI command is [`consul acl token read -self`](/consul/commands/acl/token/read#self). ### Sample Request @@ -380,16 +380,16 @@ This endpoint updates an existing ACL token. | `PUT` | `/acl/token/:AccessorID` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `acl:write` | -The corresponding CLI command is [`consul acl token update`](/commands/acl/token/update). +The corresponding CLI command is [`consul acl token update`](/consul/commands/acl/token/update). ### Path Parameters @@ -429,7 +429,7 @@ The corresponding CLI command is [`consul acl token update`](/commands/acl/token enables role renaming without breaking tokens. - `ServiceIdentities` `(array)` - The list of [service - identities](/docs/security/acl#service-identities) that should be + identities](/consul/docs/security/acl#service-identities) that should be applied to the token. Added in Consul 1.5.0. - `ServiceName` `(string: )` - The name of the service. The name @@ -443,7 +443,7 @@ The corresponding CLI command is [`consul acl token update`](/commands/acl/token but may in the future. - `NodeIdentities` `(array)` - The list of [node - identities](/docs/security/acl#node-identities) that should be + identities](/consul/docs/security/acl#node-identities) that should be applied to the token. Added in Consul 1.8.1. - `NodeName` `(string: )` - The name of the node. The name @@ -538,16 +538,16 @@ This endpoint clones an existing ACL token. | `PUT` | `/acl/token/:AccessorID/clone` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `acl:write` | -The corresponding CLI command is [`consul acl token clone`](/commands/acl/token/clone). +The corresponding CLI command is [`consul acl token clone`](/consul/commands/acl/token/clone). ### Path Parameters @@ -623,16 +623,16 @@ Even though the return type is application/json, the value is either true or false, indicating whether the delete succeeded. The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `acl:write` | -The corresponding CLI command is [`consul acl token delete`](/commands/acl/token/delete). +The corresponding CLI command is [`consul acl token delete`](/consul/commands/acl/token/delete). ### Path Parameters @@ -665,16 +665,16 @@ This endpoint lists all the ACL tokens. | `GET` | `/acl/tokens` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `YES` | `all` | `none` | `acl:read` | -The corresponding CLI command is [`consul acl token list`](/commands/acl/token/list). +The corresponding CLI command is [`consul acl token list`](/consul/commands/acl/token/list). ### Query Parameters diff --git a/website/content/api-docs/admin-partitions.mdx b/website/content/api-docs/admin-partitions.mdx index 7078cbfbf0..4c728e85d3 100644 --- a/website/content/api-docs/admin-partitions.mdx +++ b/website/content/api-docs/admin-partitions.mdx @@ -23,7 +23,7 @@ This endpoint creates a new partition and has the following characteristics: | URL path | `/v1/partition` | | Response type | `application/json` | | [Required ACLs] | `operator:write` | -| Corresponding CLI command | [`consul partition create`](/commands/partition#create) | +| Corresponding CLI command | [`consul partition create`](/consul/commands/partition#create) | | [Consistency modes] | N/A | | [Blocking queries] | N/A | | [Agent caching] | N/A | @@ -74,7 +74,7 @@ This endpoint reads a partition with the given name and has the following charac | URL path | `/v1/partition/:name` | | Response type | `application/json` | | [Required ACLs] | `operator:read`; however, a non-anonymous token can always read its own partition | -| Corresponding CLI command | [`consul partition read`](/commands/partition#read) | +| Corresponding CLI command | [`consul partition read`](/consul/commands/partition#read) | | [Consistency modes] | `default`, `consistent` | | [Blocking queries] | No | | [Agent caching] | No | @@ -111,7 +111,7 @@ This endpoint updates a partition description and has the following characterist | URL path | `/v1/partition/:name` | | Response type | `application/json` | | [Required ACLs] | `operator:write` | -| Corresponding CLI command | [`consul partition write`](/commands/partition#write) | +| Corresponding CLI command | [`consul partition write`](/consul/commands/partition#write) | | [Consistency modes] | N/A | | [Blocking queries] | N/A | | [Agent caching] | N/A | @@ -173,7 +173,7 @@ This endpoint has the following characteristics: | URL path | `/v1/partition/:name` | | Response type | none; success or failure is indicated by the HTTP response status code | | [Required ACLs] | `operator:write` | -| Corresponding CLI command | [`consul partition delete`](/commands/partition#delete) | +| Corresponding CLI command | [`consul partition delete`](/consul/commands/partition#delete) | | [Consistency modes] | N/A | | [Blocking queries] | N/A | | [Agent caching] | N/A | @@ -212,7 +212,7 @@ This endpoint lists all the partitions and has the following characteristics: | URL path | `/v1/partitions` | | Response type | `application/json` | | [Required ACLs] | `operator:read` | -| Corresponding CLI command | [`consul partition list`](/commands/partition#list) | +| Corresponding CLI command | [`consul partition list`](/consul/commands/partition#list) | | [Consistency modes] | `default`, `consistent` | | [Blocking queries] | No | | [Agent caching] | No | diff --git a/website/content/api-docs/agent/check.mdx b/website/content/api-docs/agent/check.mdx index 98f33cf328..d29f0de8fc 100644 --- a/website/content/api-docs/agent/check.mdx +++ b/website/content/api-docs/agent/check.mdx @@ -7,7 +7,7 @@ description: The /agent/check endpoints interact with checks on the local agent # Check - Agent HTTP API Consul's health check capabilities are described in the -[health checks overview](/docs/discovery/checks). +[health checks overview](/consul/docs/discovery/checks). The `/agent/check` endpoints interact with health checks managed by the local agent in Consul. These should not be confused with checks in the catalog. @@ -21,7 +21,7 @@ using the HTTP API. It is important to note that the checks known by the agent may be different from those reported by the catalog. This is usually due to changes being made while there is no leader elected. The agent performs active -[anti-entropy](/docs/architecture/anti-entropy), so in most situations +[anti-entropy](/consul/docs/architecture/anti-entropy), so in most situations everything will be in sync within a few seconds. @include 'http_api_results_filtered_by_acls.mdx' @@ -31,10 +31,10 @@ everything will be in sync within a few seconds. | `GET` | `/agent/checks` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------ | @@ -109,10 +109,10 @@ check and keeping the Catalog in sync. | `PUT` | `/agent/check/register` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | -------------------------- | @@ -313,10 +313,10 @@ not exist, no action is taken. | `PUT` | `/agent/check/deregister/:check_id` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | -------------------------- | @@ -351,10 +351,10 @@ This endpoint is used with a TTL type check to set the status of the check to | `PUT` | `/agent/check/pass/:check_id` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | -------------------------- | @@ -390,10 +390,10 @@ This endpoint is used with a TTL type check to set the status of the check to | `PUT` | `/agent/check/warn/:check_id` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | -------------------------- | @@ -424,7 +424,7 @@ This endpoint is used with a TTL type check to set the status of the check to `critical` and to reset the TTL clock. If you want to manually mark a service as unhealthy, -use [maintenance mode](/api-docs/agent#enable-maintenance-mode) +use [maintenance mode](/consul/api-docs/agent#enable-maintenance-mode) instead of defining a TTL health check and using this endpoint. | Method | Path | Produces | @@ -432,10 +432,10 @@ instead of defining a TTL health check and using this endpoint. | `PUT` | `/agent/check/fail/:check_id` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | -------------------------- | @@ -466,7 +466,7 @@ This endpoint is used with a TTL type check to set the status of the check and to reset the TTL clock. If you want to manually mark a service as unhealthy, -use [maintenance mode](/api-docs/agent#enable-maintenance-mode) +use [maintenance mode](/consul/api-docs/agent#enable-maintenance-mode) instead of defining a TTL health check and using this endpoint. | Method | Path | Produces | @@ -474,10 +474,10 @@ instead of defining a TTL health check and using this endpoint. | `PUT` | `/agent/check/update/:check_id` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | -------------------------- | diff --git a/website/content/api-docs/agent/connect.mdx b/website/content/api-docs/agent/connect.mdx index f706fd47e8..68944b404b 100644 --- a/website/content/api-docs/agent/connect.mdx +++ b/website/content/api-docs/agent/connect.mdx @@ -8,10 +8,10 @@ description: >- # Connect - Agent HTTP API -The `/agent/connect` endpoints interact with [Connect](/docs/connect) +The `/agent/connect` endpoints interact with [Connect](/consul/docs/connect) with agent-local operations. -These endpoints may mirror the [non-agent Connect endpoints](/api-docs/connect) +These endpoints may mirror the [non-agent Connect endpoints](/consul/api-docs/connect) in some cases. Almost all agent-local Connect endpoints perform local caching to optimize performance of Connect without having to make requests to the server. @@ -22,13 +22,13 @@ defined as _deny_ intentions during evaluation, as this endpoint is only suited for networking layer 4 (e.g. TCP) integration. For performance and reliability reasons it is desirable to implement intention enforcement by listing [intentions that match the -destination](/api-docs/connect/intentions#list-matching-intentions) and representing +destination](/consul/api-docs/connect/intentions#list-matching-intentions) and representing them in the native configuration of the proxy itself (such as RBAC for Envoy). This endpoint tests whether a connection attempt is authorized between two services. This is the primary API that must be implemented by -[proxies](/docs/connect/proxies) or -[native integrations](/docs/connect/native) +[proxies](/consul/docs/connect/proxies) or +[native integrations](/consul/docs/connect/native) that wish to integrate with Connect. Prior to calling this API, it is expected that the client TLS certificate has been properly verified against the current CA roots. @@ -43,10 +43,10 @@ connection attempt. | `POST` | `/agent/connect/authorize` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | -------------------- | --------------- | @@ -104,11 +104,11 @@ $ curl \ ## Certificate Authority (CA) Roots This endpoint returns the trusted certificate authority (CA) root certificates. -This is used by [proxies](/docs/connect/proxies) or -[native integrations](/docs/connect/native) to verify served client +This is used by [proxies](/consul/docs/connect/proxies) or +[native integrations](/consul/docs/connect/native) to verify served client or server certificates are valid. -This is equivalent to the [non-Agent Connect endpoint](/api-docs/connect), +This is equivalent to the [non-Agent Connect endpoint](/consul/api-docs/connect), but the response of this request is cached locally at the agent. This allows for very fast response times and for fail open behavior if the server is unavailable. This endpoint should be used by proxies and native integrations. @@ -118,10 +118,10 @@ unavailable. This endpoint should be used by proxies and native integrations. | `GET` | `/agent/connect/ca/roots` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | -------------------- | ------------ | @@ -168,7 +168,7 @@ connections and is also used as the client certificate for establishing outbound connections to other services. The agent generates a CSR locally and calls the -[CA sign API](/api-docs/connect/ca) to sign it. The resulting certificate +[CA sign API](/consul/api-docs/connect/ca) to sign it. The resulting certificate is cached and returned by this API until it is near expiry or the root certificates change. @@ -186,10 +186,10 @@ wait for certificate rotations. | `GET` | `/agent/connect/ca/leaf/:service` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | -------------------- | --------------- | diff --git a/website/content/api-docs/agent/index.mdx b/website/content/api-docs/agent/index.mdx index 0027c3a41e..f84bad1be0 100644 --- a/website/content/api-docs/agent/index.mdx +++ b/website/content/api-docs/agent/index.mdx @@ -12,7 +12,7 @@ The `/agent` endpoints are used to interact with the local Consul agent. Usually, services and checks are registered with an agent which then takes on the burden of keeping that data synchronized with the cluster. For example, the agent registers services and checks with the Catalog and performs -[anti-entropy](/docs/architecture/anti-entropy) to recover from outages. +[anti-entropy](/consul/docs/architecture/anti-entropy) to recover from outages. In addition to these endpoints, additional endpoints are grouped in the navigation for `Checks` and `Services`. @@ -31,10 +31,10 @@ GitHub issue to discuss your use case. | `GET` | `/agent/host` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | --------------- | @@ -220,16 +220,16 @@ by agent. The strongly consistent view of nodes is instead provided by | `GET` | `/agent/members` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `node:read` | -The corresponding CLI command is [`consul members`](/commands/members). +The corresponding CLI command is [`consul members`](/consul/commands/members). ### Query Parameters @@ -288,10 +288,10 @@ to change without notice or deprecation. | `GET` | `/agent/self` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | @@ -360,7 +360,7 @@ This endpoint instructs the agent to reload its configuration. Any errors encountered during this process are returned. Not all configuration options are reloadable. See the -[Reloadable Configuration](/docs/agent/config#reloadable-configuration) +[Reloadable Configuration](/consul/docs/agent/config#reloadable-configuration) section on the agent options page for details on which options are supported. | Method | Path | Produces | @@ -368,16 +368,16 @@ section on the agent options page for details on which options are supported. | `PUT` | `/agent/reload` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------- | | `NO` | `none` | `none` | `agent:write` | -The corresponding CLI command is [`consul reload`](/commands/reload). +The corresponding CLI command is [`consul reload`](/consul/commands/reload). ### Sample Request @@ -401,16 +401,16 @@ restart. | `PUT` | `/agent/maintenance` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `node:write` | -The corresponding CLI command is [`consul maint`](/commands/maint). +The corresponding CLI command is [`consul maint`](/consul/commands/maint). ### Query Parameters @@ -433,12 +433,12 @@ $ curl \ ## View Metrics This endpoint will dump the metrics for the most recent finished interval. -For more information about metrics, see the [telemetry](/docs/agent/telemetry) +For more information about metrics, see the [telemetry](/consul/docs/agent/telemetry) page. In order to enable [Prometheus](https://prometheus.io/) support, you need to use the configuration directive -[`prometheus_retention_time`](/docs/agent/config/config-files#telemetry-prometheus_retention_time). +[`prometheus_retention_time`](/consul/docs/agent/config/config-files#telemetry-prometheus_retention_time). Since Consul 1.7.2 this endpoint will also automatically switch output format if the request contains an `Accept` header with a compatible MIME type such as @@ -460,10 +460,10 @@ endpoint. | `GET` | `/agent/metrics?format=prometheus` | `text/plain; version=0.0.4; charset=utf-8` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | @@ -582,10 +582,10 @@ This endpoint streams logs from the local agent until the connection is closed. | `GET` | `/agent/monitor` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | @@ -627,16 +627,16 @@ This endpoint instructs the agent to attempt to connect to a given address. | `PUT` | `/agent/join/:address` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------- | | `NO` | `none` | `none` | `agent:write` | -The corresponding CLI command is [`consul join`](/commands/join). +The corresponding CLI command is [`consul join`](/consul/commands/join). ### Path Parameters @@ -669,16 +669,16 @@ can affect cluster availability. | `PUT` | `/agent/leave` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------- | | `NO` | `none` | `none` | `agent:write` | -The corresponding CLI command is [`consul leave`](/commands/leave). +The corresponding CLI command is [`consul leave`](/consul/commands/leave). ### Sample Request @@ -708,16 +708,16 @@ the list of members entirely. | `PUT` | `/agent/force-leave/:node_name?prune` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ---------------- | | `NO` | `none` | `none` | `operator:write` | -The corresponding CLI command is [`consul force-leave`](/commands/force-leave). +The corresponding CLI command is [`consul force-leave`](/consul/commands/force-leave). ### Path Parameters @@ -745,7 +745,7 @@ $ curl \ This endpoint updates the ACL tokens currently in use by the agent. It can be used to introduce ACL tokens to the agent for the first time, or to update tokens that were initially loaded from the agent's configuration. Tokens will be persisted -only if the [`acl.enable_token_persistence`](/docs/agent/config/config-files#acl_enable_token_persistence) +only if the [`acl.enable_token_persistence`](/consul/docs/agent/config/config-files#acl_enable_token_persistence) configuration is `true`. When not being persisted, they will need to be reset if the agent is restarted. @@ -758,10 +758,10 @@ is restarted. | `PUT` | `/agent/token/replication` | `application/json` | The paths above correspond to the token names as found in the agent configuration: -[`default`](/docs/agent/config/config-files#acl_tokens_default), [`agent`](/docs/agent/config/config-files#acl_tokens_agent), -[`agent_recovery`](/docs/agent/config/config-files#acl_tokens_agent_recovery), -[`config_file_service_registration`](/docs/agent/config/config-files#acl_tokens_config_file_service_registration), -and [`replication`](/docs/agent/config/config-files#acl_tokens_replication). +[`default`](/consul/docs/agent/config/config-files#acl_tokens_default), [`agent`](/consul/docs/agent/config/config-files#acl_tokens_agent), +[`agent_recovery`](/consul/docs/agent/config/config-files#acl_tokens_agent_recovery), +[`config_file_service_registration`](/consul/docs/agent/config/config-files#acl_tokens_config_file_service_registration), +and [`replication`](/consul/docs/agent/config/config-files#acl_tokens_replication). -> **Deprecation Note:** The following paths were deprecated in version 1.11 @@ -770,7 +770,7 @@ and [`replication`](/docs/agent/config/config-files#acl_tokens_replication). | `PUT` | `/agent/token/agent_master` | `application/json` | The paths above correspond to the token names as found in the agent configuration: -[`agent_master`](/docs/agent/config/config-files#acl_tokens_agent_master). +[`agent_master`](/consul/docs/agent/config/config-files#acl_tokens_agent_master). -> **Deprecation Note:** The following paths were deprecated in version 1.4.3 @@ -782,21 +782,21 @@ The paths above correspond to the token names as found in the agent configuratio | `PUT` | `/agent/token/acl_replication_token` | `application/json` | The paths above correspond to the token names as found in the agent configuration: -[`acl_token`](/docs/agent/config/config-files#acl_token_legacy), [`acl_agent_token`](/docs/agent/config/config-files#acl_agent_token_legacy), -[`acl_agent_master_token`](/docs/agent/config/config-files#acl_agent_master_token_legacy), and -[`acl_replication_token`](/docs/agent/config/config-files#acl_replication_token_legacy). +[`acl_token`](/consul/docs/agent/config/config-files#acl_token_legacy), [`acl_agent_token`](/consul/docs/agent/config/config-files#acl_agent_token_legacy), +[`acl_agent_master_token`](/consul/docs/agent/config/config-files#acl_agent_master_token_legacy), and +[`acl_replication_token`](/consul/docs/agent/config/config-files#acl_replication_token_legacy). The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------- | | `NO` | `none` | `none` | `agent:write` | -The corresponding CLI command is [`consul acl set-agent-token`](/commands/acl/set-agent-token). +The corresponding CLI command is [`consul acl set-agent-token`](/consul/commands/acl/set-agent-token). ### JSON Request Body Schema diff --git a/website/content/api-docs/agent/service.mdx b/website/content/api-docs/agent/service.mdx index 4107e21f1a..a232c4491a 100644 --- a/website/content/api-docs/agent/service.mdx +++ b/website/content/api-docs/agent/service.mdx @@ -20,7 +20,7 @@ or added dynamically using the HTTP API. It is important to note that the services known by the agent may be different from those reported by the catalog. This is usually due to changes being made while there is no leader elected. The agent performs active -[anti-entropy](/docs/architecture/anti-entropy), so in most situations +[anti-entropy](/consul/docs/architecture/anti-entropy), so in most situations everything will be in sync within a few seconds. @include 'http_api_results_filtered_by_acls.mdx' @@ -30,10 +30,10 @@ everything will be in sync within a few seconds. | `GET` | `/agent/services` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | -------------- | @@ -130,13 +130,13 @@ following selectors and filter operations being supported: This endpoint was added in Consul 1.3.0 and returns the full service definition for a single service instance registered on the local agent. It is used by -[Connect proxies](/docs/connect/proxies) to discover the embedded proxy +[Connect proxies](/consul/docs/connect/proxies) to discover the embedded proxy configuration that was registered with the instance. It is important to note that the services known by the agent may be different from those reported by the catalog. This is usually due to changes being made while there is no leader elected. The agent performs active -[anti-entropy](/docs/architecture/anti-entropy), so in most situations +[anti-entropy](/consul/docs/architecture/anti-entropy), so in most situations everything will be in sync within a few seconds. | Method | Path | Produces | @@ -144,10 +144,10 @@ everything will be in sync within a few seconds. | `GET` | `/agent/service/:service_id` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ----------------- | ----------------- | ------------- | -------------- | @@ -228,9 +228,9 @@ $ curl \ ``` The response has the same structure as the [service -definition](/docs/discovery/services) with one extra field `ContentHash` which +definition](/consul/docs/discovery/services) with one extra field `ContentHash` which contains the [hash-based blocking -query](/api-docs/features/blocking#hash-based-blocking-queries) hash for the result. The +query](/consul/api-docs/features/blocking#hash-based-blocking-queries) hash for the result. The same hash is also present in `X-Consul-ContentHash`. ## Get local service health @@ -248,10 +248,10 @@ the URL or use Mime Content negotiation by specifying a HTTP Header | `GET` | `/agent/health/service/name/:service_name?format=text` | `text/plain` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | -------------- | @@ -278,7 +278,7 @@ Those endpoints might be useful for the following use-cases: ##### Note If you know the ID of service you want to target, it is recommended to use -[`/v1/agent/health/service/id/:service_id`](/api-docs/agent/service#get-local-service-health-by-id) +[`/v1/agent/health/service/id/:service_id`](/consul/api-docs/agent/service#get-local-service-health-by-id) so you have the result for the service only. When requesting `/v1/agent/health/service/name/:service_name`, the caller will receive the worst state of all services having the given name. @@ -423,7 +423,7 @@ Retrieve the health state of a specific service on the local agent by ID. | `GET` | `/agent/health/service/id/:service_id?format=text` | `text/plain` | The supported request parameters are the same as -[`/v1/agent/health/service/name/:service_name`](/api-docs/agent/service#get-local-service-health). +[`/v1/agent/health/service/name/:service_name`](/consul/api-docs/agent/service#get-local-service-health). ### Sample Requests @@ -579,16 +579,16 @@ For "connect-proxy" kind services, the `service:write` ACL for the | `PUT` | `/agent/service/register` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | --------------- | | `NO` | `none` | `none` | `service:write` | -The corresponding CLI command is [`consul services register`](/commands/services/register). +The corresponding CLI command is [`consul services register`](/consul/commands/services/register). ### Query Parameters @@ -599,13 +599,13 @@ The corresponding CLI command is [`consul services register`](/commands/services ### JSON Request Body Schema -Note that this endpoint, unlike most also [supports `snake_case`](/docs/discovery/services#service-definition-parameter-case) +Note that this endpoint, unlike most also [supports `snake_case`](/consul/docs/discovery/services#service-definition-parameter-case) service definition keys for compatibility with the config file format. - `Name` `(string: )` - Specifies the logical name of the service. Many service instances may share the same logical service name. We recommend using [valid DNS labels](https://en.wikipedia.org/wiki/Hostname#Restrictions_on_valid_hostnames) - for [compatibility with external DNS](/docs/discovery/services#service-and-tag-names-with-dns). + for [compatibility with external DNS](/consul/docs/discovery/services#service-and-tag-names-with-dns). - `ID` `(string: "")` - Specifies a unique ID for this service. This must be unique per _agent_. This defaults to the `Name` parameter if not provided. @@ -613,7 +613,7 @@ service definition keys for compatibility with the config file format. - `Tags` `(array: nil)` - Specifies a list of tags to assign to the service. These tags can be used for later filtering and are exposed via the APIs. We recommend using [valid DNS labels](https://en.wikipedia.org/wiki/Hostname#Restrictions_on_valid_hostnames) - for [compatibility with external DNS](/docs/discovery/services#service-and-tag-names-with-dns) + for [compatibility with external DNS](/consul/docs/discovery/services#service-and-tag-names-with-dns) - `Address` `(string: "")` - Specifies the address of the service. If not provided, the agent's address is used as the address for the service during @@ -634,28 +634,28 @@ service definition keys for compatibility with the config file format. - `Kind` `(string: "")` - The kind of service. Defaults to "" which is a typical Consul service. This value may also be "connect-proxy" for - [Connect](/docs/connect) proxies representing another service, - "mesh-gateway" for instances of a [mesh gateway](/docs/connect/gateways/mesh-gateway#connect-proxy-configuration), - "terminating-gateway" for instances of a [terminating gateway](/docs/connect/gateways/terminating-gateway), - or "ingress-gateway" for instances of a [ingress gateway](/docs/connect/gateways/ingress-gateway). + [Connect](/consul/docs/connect) proxies representing another service, + "mesh-gateway" for instances of a [mesh gateway](/consul/docs/connect/gateways/mesh-gateway#connect-proxy-configuration), + "terminating-gateway" for instances of a [terminating gateway](/consul/docs/connect/gateways/terminating-gateway), + or "ingress-gateway" for instances of a [ingress gateway](/consul/docs/connect/gateways/ingress-gateway). - `Proxy` `(Proxy: nil)` - From 1.2.3 on, specifies the configuration for a Connect service proxy instance. This is only valid if `Kind` defines a proxy or gateway. - See the [Proxy documentation](/docs/connect/registration/service-registration) + See the [Proxy documentation](/consul/docs/connect/registration/service-registration) for full details. - `Connect` `(Connect: nil)` - Specifies the - [configuration for Connect](/docs/connect/configuration). See the + [configuration for Connect](/consul/docs/connect/configuration). See the [Connect Structure](#connect-structure) section below for supported fields. - `Check` `(Check: nil)` - Specifies a check. Please see the - [check documentation](/api-docs/agent/check) for more information about the + [check documentation](/consul/api-docs/agent/check) for more information about the accepted fields. If you don't provide a name or id for the check then they will be generated. To provide a custom id and/or name set the `CheckID` and/or `Name` field. - `Checks` `(array: nil)` - Specifies a list of checks. Please see the - [check documentation](/api-docs/agent/check) for more information about the + [check documentation](/consul/api-docs/agent/check) for more information about the accepted fields. If you don't provide a name or id for the check then they will be generated. To provide a custom id and/or name set the `CheckID` and/or `Name` field. The automatically generated `Name` and `CheckID` depend @@ -665,7 +665,7 @@ service definition keys for compatibility with the config file format. - `EnableTagOverride` `(bool: false)` - Specifies to disable the anti-entropy feature for this service's tags. If `EnableTagOverride` is set to `true` then - external agents can update this service in the [catalog](/api-docs/catalog) + external agents can update this service in the [catalog](/consul/api-docs/catalog) and modify the tags. Subsequent local sync operations by this agent will ignore the updated tags. For instance, if an external agent modified both the tags and the port for this service and `EnableTagOverride` was set to `true` @@ -677,7 +677,7 @@ service definition keys for compatibility with the config file format. modifications would be lost. - `Weights` `(Weights: nil)` - Specifies weights for the service. Please see the - [service documentation](/docs/discovery/services) for more information about + [service documentation](/consul/docs/discovery/services) for more information about weights. If this field is not provided weights will default to `{"Passing": 1, "Warning": 1}`. @@ -687,7 +687,7 @@ service definition keys for compatibility with the config file format. are independent of one another. Updating the tags for the service registered on one node is independent of the same service (by name) registered on another node. If `EnableTagOverride` is not specified the default value is - `false`. See [anti-entropy syncs](/docs/architecture/anti-entropy) for + `false`. See [anti-entropy syncs](/consul/docs/architecture/anti-entropy) for more info. #### Connect Structure @@ -695,17 +695,17 @@ service definition keys for compatibility with the config file format. For the `Connect` field, the parameters are: - `Native` `(bool: false)` - Specifies whether this service supports - the [Connect](/docs/connect) protocol [natively](/docs/connect/native). + the [Connect](/consul/docs/connect) protocol [natively](/consul/docs/connect/native). If this is true, then Connect proxies, DNS queries, etc. will be able to service discover this service. - `Proxy` `(Proxy: nil)` - - [**Deprecated**](/docs/connect/proxies/managed-deprecated) Specifies that + [**Deprecated**](/consul/docs/connect/proxies/managed-deprecated) Specifies that a managed Connect proxy should be started for this service instance, and optionally provides configuration for the proxy. The format is as documented - in [Managed Proxy Deprecation](/docs/connect/proxies/managed-deprecated). + in [Managed Proxy Deprecation](/consul/docs/connect/proxies/managed-deprecated). - `SidecarService` `(ServiceDefinition: nil)` - Specifies an optional nested service definition to register. For more information see - [Sidecar Service Registration](/docs/connect/registration/sidecar-service). + [Sidecar Service Registration](/consul/docs/connect/registration/sidecar-service). ### Sample Payload @@ -755,16 +755,16 @@ is an associated check, that is also deregistered. | `PUT` | `/agent/service/deregister/:service_id` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | --------------- | | `NO` | `none` | `none` | `service:write` | -The corresponding CLI command is [`consul services deregister`](/commands/services/deregister). +The corresponding CLI command is [`consul services deregister`](/consul/commands/services/deregister). ### Path Parameters @@ -795,10 +795,10 @@ will be automatically restored on agent restart. | `PUT` | `/agent/service/maintenance/:service_id` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | --------------- | diff --git a/website/content/api-docs/api-structure.mdx b/website/content/api-docs/api-structure.mdx index d682c687c0..655399e793 100644 --- a/website/content/api-docs/api-structure.mdx +++ b/website/content/api-docs/api-structure.mdx @@ -44,7 +44,7 @@ $ curl \ this method is highly discouraged because the token can show up in access logs as part of the URL. The `?token=` query parameter is deprecated and will be removed in Consul 1.17. -To learn more about the ACL system read the [documentation](/docs/security/acl). +To learn more about the ACL system read the [documentation](/consul/docs/security/acl). ## Version Prefix @@ -89,11 +89,11 @@ However, we generally recommend using resource names that don't require URL-enco Depending on the validation that Consul applies to a resource name, Consul may still reject a request if it considers the resource name invalid for that endpoint. And even if Consul considers the resource name valid, it may degrade other functionality, -such as failed [DNS lookups](/docs/discovery/dns) +such as failed [DNS lookups](/consul/docs/discovery/dns) for nodes or services with names containing invalid DNS characters. This HTTP API capability also allows the -[CLI to accept arguments with URL-invalid characters](/commands#arguments-with-url-invalid-characters). +[CLI to accept arguments with URL-invalid characters](/consul/commands#arguments-with-url-invalid-characters). ### Invalid Characters @@ -103,7 +103,7 @@ The linefeed character (`%0a`) will cause a request to be rejected even if it is Consul 0.7 added the ability to translate addresses in HTTP response based on the configuration setting for -[`translate_wan_addrs`](/docs/agent/config/config-files#translate_wan_addrs). In order +[`translate_wan_addrs`](/consul/docs/agent/config/config-files#translate_wan_addrs). In order to allow clients to know if address translation is in effect, the `X-Consul-Translate-Addresses` header will be added if translation is enabled, and will have a value of `true`. If translation is not enabled then this header @@ -114,9 +114,9 @@ will not be present. All API responses for Consul versions after 1.9 will include an HTTP response header `X-Consul-Default-ACL-Policy` set to either "allow" or "deny" which mirrors the current value of the agent's -[`acl.default_policy`](/docs/agent/config/config-files#acl_default_policy) option. +[`acl.default_policy`](/consul/docs/agent/config/config-files#acl_default_policy) option. -This is also the default [intention](/docs/connect/intentions) enforcement +This is also the default [intention](/consul/docs/connect/intentions) enforcement action if no intention matches. This is returned even if ACLs are disabled. diff --git a/website/content/api-docs/catalog.mdx b/website/content/api-docs/catalog.mdx index 89ad4bf201..b9a8c7bbd7 100644 --- a/website/content/api-docs/catalog.mdx +++ b/website/content/api-docs/catalog.mdx @@ -16,18 +16,18 @@ API methods look similar. This endpoint is a low-level mechanism for registering or updating entries in the catalog. It is usually preferable to instead use the -[agent endpoints](/api-docs/agent) for registration as they are simpler and -perform [anti-entropy](/docs/architecture/anti-entropy). +[agent endpoints](/consul/api-docs/agent) for registration as they are simpler and +perform [anti-entropy](/consul/docs/architecture/anti-entropy). | Method | Path | Produces | | ------ | ------------------- | ------------------ | | `PUT` | `/catalog/register` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | -------------------------- | @@ -59,17 +59,17 @@ The table below shows this endpoint's support for provided, it will be defaulted to the value of the `Service.Service` property. Only one service with a given `ID` may be present per node. We recommend using [valid DNS labels](https://en.wikipedia.org/wiki/Hostname#Restrictions_on_valid_hostnames) - for service definition names for [compatibility with external DNS](/docs/discovery/services#service-and-tag-names-with-dns). + for service definition names for [compatibility with external DNS](/consul/docs/discovery/services#service-and-tag-names-with-dns). The service `Tags`, `Address`, `Meta`, and `Port` fields are all optional. For more information about these fields and the implications of setting them, - see the [Service - Agent API](/api-docs/agent/service) page + see the [Service - Agent API](/consul/api-docs/agent/service) page as registering services differs between using this or the Services Agent endpoint. - `Check` `(Check: nil)` - Specifies to register a check. The register API manipulates the health check entry in the Catalog, but it does not setup the script, TTL, or HTTP check to monitor the node's health. To truly enable a new health check, the check must either be provided in agent configuration or set - via the [agent endpoint](agent). + via the [agent endpoint](https://consul.io/agent). The `CheckID` can be omitted and will default to the value of `Name`. As with `Service.ID`, the `CheckID` must be unique on this node. `Notes` is an @@ -79,7 +79,7 @@ The table below shows this endpoint's support for check. The `Status` must be one of `passing`, `warning`, or `critical`. The `Definition` field can be provided with details for a TCP or HTTP health - check. For more information, see the [Health Checks](/docs/discovery/checks) page. + check. For more information, see the [Health Checks](/consul/docs/discovery/checks) page. Multiple checks can be provided by replacing `Check` with `Checks` and sending an array of `Check` objects. @@ -168,18 +168,18 @@ $ curl \ This endpoint is a low-level mechanism for directly removing entries from the Catalog. It is usually preferable to instead use the -[agent endpoints](/api-docs/agent) for deregistration as they are simpler and -perform [anti-entropy](/docs/architecture/anti-entropy). +[agent endpoints](/consul/api-docs/agent) for deregistration as they are simpler and +perform [anti-entropy](/consul/docs/architecture/anti-entropy). | Method | Path | Produces | | ------ | --------------------- | ------------------ | | `PUT` | `/catalog/deregister` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | -------------------------- | @@ -263,16 +263,16 @@ Consul servers are routable. | `GET` | `/catalog/datacenters` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `simple` | `none` | -The corresponding CLI command is [`consul catalog datacenters`](/commands/catalog/datacenters). +The corresponding CLI command is [`consul catalog datacenters`](/consul/commands/catalog/datacenters). ### Sample Request @@ -298,16 +298,16 @@ This endpoint and returns the nodes registered in a given datacenter. | `GET` | `/catalog/nodes` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `YES` | `all` | `none` | `node:read` | -The corresponding CLI command is [`consul catalog nodes`](/commands/catalog/nodes). +The corresponding CLI command is [`consul catalog nodes`](/consul/commands/catalog/nodes). ### Query Parameters @@ -394,16 +394,16 @@ This endpoint returns the services registered in a given datacenter. | `GET` | `/catalog/services` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | -------------------- | -------------- | | `YES` | `all` | `background refresh` | `service:read` | -The corresponding CLI command is [`consul catalog services`](/commands/catalog/services). +The corresponding CLI command is [`consul catalog services`](/consul/commands/catalog/services). ### Query Parameters @@ -499,10 +499,10 @@ This endpoint returns the nodes providing a service in a given datacenter. | `GET` | `/catalog/service/:service_name` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | -------------------- | ------------------------ | @@ -539,10 +539,10 @@ The table below shows this endpoint's support for - `merge-central-config` - Include this flag in a request for `connect-proxy` kind or `*-gateway` kind services to return a fully resolved service definition that includes merged values from the - [proxy-defaults/global](/docs/connect/config-entries/proxy-defaults) and - [service-defaults/:service](/docs/connect/config-entries/service-defaults) config entries. + [proxy-defaults/global](/consul/docs/connect/config-entries/proxy-defaults) and + [service-defaults/:service](/consul/docs/connect/config-entries/service-defaults) config entries. Returning a fully resolved service definition is useful when a service was registered using the - [/catalog/register](/api-docs/catalog#register_entity) endpoint, which does not automatically merge config entries. + [/catalog/register](/consul/api-docs/catalog#register_entity) endpoint, which does not automatically merge config entries. - `ns` `(string: "")` - Specifies the namespace of the services you lookup. You can also [specify the namespace through other methods](#methods-to-specify-namespace). @@ -647,12 +647,12 @@ $ curl \ service instance. This includes both the address as well as the port. - `ServiceKind` is the kind of service, usually "". See the Agent - [service registration API](/api-docs/agent/service#kind) for more information. + [service registration API](/consul/api-docs/agent/service#kind) for more information. - `ServiceProxy` is the proxy config as specified in - [Connect Proxies](/docs/connect/proxies). + [Connect Proxies](/consul/docs/connect/proxies). -- `ServiceConnect` are the [Connect](/docs/connect) settings. The +- `ServiceConnect` are the [Connect](/consul/docs/connect) settings. The value of this struct is equivalent to the `Connect` field for service registration. @@ -707,7 +707,7 @@ following selectors and filter operations being supported: ## List Nodes for Connect-capable Service This endpoint returns the nodes providing a -[Connect-capable](/docs/connect) service in a given datacenter. +[Connect-capable](/consul/docs/connect) service in a given datacenter. This will include both proxies and native integrations. A service may register both Connect-capable and incapable services at the same time, so this endpoint may be used to filter only the Connect-capable endpoints. @@ -719,7 +719,7 @@ so this endpoint may be used to filter only the Connect-capable endpoints. | `GET` | `/catalog/connect/:service` | `application/json` | Parameters and response format are the same as -[`/catalog/service/:service_name`](/api-docs/catalog#list-nodes-for-service). +[`/catalog/service/:service_name`](/consul/api-docs/catalog#list-nodes-for-service). ## Retrieve Map of Services for a Node @@ -732,10 +732,10 @@ This endpoint returns the node's registered services. | `GET` | `/catalog/node/:node_name` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------ | @@ -861,10 +861,10 @@ This endpoint returns the node's registered services. | `GET` | `/catalog/node-services/:node_name` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------ | @@ -884,10 +884,10 @@ The table below shows this endpoint's support for - `merge-central-config` - Include this flag in a request for `connect-proxy` kind or `*-gateway` kind services to return a fully resolved service definition that includes merged values from the - [proxy-defaults/global](/docs/connect/config-entries/proxy-defaults) and - [service-defaults/:service](/docs/connect/config-entries/service-defaults) config entries. + [proxy-defaults/global](/consul/docs/connect/config-entries/proxy-defaults) and + [service-defaults/:service](/consul/docs/connect/config-entries/service-defaults) config entries. Returning a fully resolved service definition is useful when a service was registered using the - [/catalog/register](/api-docs/catalog#register_entity) endpoint, which does not automatically merge config entries. + [/catalog/register](/consul/api-docs/catalog#register_entity) endpoint, which does not automatically merge config entries. - `ns` `(string: "")` - Specifies the namespace of the services you lookup. The namespace may be specified as '\*' to return results for all namespaces. @@ -1002,10 +1002,10 @@ This endpoint returns the services associated with an ingress gateway or termina | `GET` | `/catalog/gateway-services/:gateway` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | -------------- | @@ -1113,7 +1113,7 @@ $ curl \ - `Service.Namespace` is the Consul Enterprise namespace of a service associated with the gateway - `GatewayKind` is the kind of service, will be one of "ingress-gateway" or "terminating-gateway". See the Agent - [service registration API](/api-docs/agent/service#kind) for more information. + [service registration API](/consul/api-docs/agent/service#kind) for more information. - `CAFile` is the path to a CA file the gateway will use for TLS origination to the associated service diff --git a/website/content/api-docs/config.mdx b/website/content/api-docs/config.mdx index 128cb8252c..3c49e0c8d3 100644 --- a/website/content/api-docs/config.mdx +++ b/website/content/api-docs/config.mdx @@ -10,9 +10,9 @@ description: |- The `/config` endpoints create, update, delete and query central configuration entries registered with Consul. See the -[agent configuration](/docs/agent/config/config-files#enable_central_service_config) +[agent configuration](/consul/docs/agent/config/config-files#enable_central_service_config) for more information on how to enable this functionality for centrally -configuring services and [configuration entries docs](/docs/agent/config-entries) for a description +configuring services and [configuration entries docs](/consul/docs/agent/config-entries) for a description of the configuration entries content. ## Apply Configuration @@ -24,10 +24,10 @@ This endpoint creates or updates the given config entry. | `PUT` | `/config` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------------------------------- | @@ -48,7 +48,7 @@ The table below shows this endpoint's support for | service-splitter | `service:write` | | terminating-gateway | `operator:write` | -The corresponding CLI command is [`consul config write`](/commands/config/write). +The corresponding CLI command is [`consul config write`](/consul/commands/config/write). ### Query Parameters @@ -91,10 +91,10 @@ This endpoint returns a specific config entry. | `GET` | `/config/:kind/:name` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | -------------------------- | @@ -113,7 +113,7 @@ The table below shows this endpoint's support for | service-splitter | `service:read` | | terminating-gateway | `service:read` | -The corresponding CLI command is [`consul config read`](/commands/config/read). +The corresponding CLI command is [`consul config read`](/consul/commands/config/read). ### Path Parameters @@ -162,10 +162,10 @@ This endpoint returns all config entries of the given kind. | `GET` | `/config/:kind` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | -------------------------- | @@ -184,7 +184,7 @@ The table below shows this endpoint's support for | service-splitter | `service:read` | | terminating-gateway | `service:read` | -The corresponding CLI command is [`consul config list`](/commands/config/list). +The corresponding CLI command is [`consul config list`](/consul/commands/config/list). ### Path Parameters @@ -236,10 +236,10 @@ This endpoint deletes the given config entry. | `DELETE` | `/config/:kind/:name` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------------------------------- | @@ -258,7 +258,7 @@ The table below shows this endpoint's support for | service-splitter | `service:write` | | terminating-gateway | `operator:write ` | -The corresponding CLI command is [`consul config delete`](/commands/config/delete). +The corresponding CLI command is [`consul config delete`](/consul/commands/config/delete). ### Path Parameters diff --git a/website/content/api-docs/connect/ca.mdx b/website/content/api-docs/connect/ca.mdx index 2229b1566c..75a1e2ab91 100644 --- a/website/content/api-docs/connect/ca.mdx +++ b/website/content/api-docs/connect/ca.mdx @@ -21,10 +21,10 @@ the cluster. | `GET` | `/connect/ca/roots` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | @@ -113,10 +113,10 @@ This endpoint returns the current CA configuration. | `GET` | `/connect/ca/configuration` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ----------------------------- | @@ -125,7 +125,7 @@ The table below shows this endpoint's support for 1 ACL required was operator:read prior to versions 1.8.6, 1.7.10, and 1.6.10. -The corresponding CLI command is [`consul connect ca get-config`](/commands/connect/ca#get-config). +The corresponding CLI command is [`consul connect ca get-config`](/consul/commands/connect/ca#get-config). ### Sample Request @@ -151,30 +151,30 @@ $ curl \ ## Update CA Configuration This endpoint updates the configuration for the CA. If this results in a -new root certificate being used, the [Root Rotation](/docs/connect/ca#root-certificate-rotation) process will be triggered. +new root certificate being used, the [Root Rotation](/consul/docs/connect/ca#root-certificate-rotation) process will be triggered. | Method | Path | Produces | | ------ | --------------------------- | ------------------ | | `PUT` | `/connect/ca/configuration` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ---------------- | | `NO` | `none` | `none` | `operator:write` | -The corresponding CLI command is [`consul connect ca set-config`](/commands/connect/ca#set-config). +The corresponding CLI command is [`consul connect ca set-config`](/consul/commands/connect/ca#set-config). ~> **If currently using Vault CA provider:** If you intend to change the CA provider from Vault to another, - or to change the Vault provider's [`RootPKIPath`](/docs/connect/ca/vault#rootpkipath), + or to change the Vault provider's [`RootPKIPath`](/consul/docs/connect/ca/vault#rootpkipath), you must temporarily elevate the privileges of the Vault token or auth method in use as described in the - [Vault CA provider documentation](/docs/connect/ca/vault#additional-vault-acl-policies-for-sensitive-operations). + [Vault CA provider documentation](/consul/docs/connect/ca/vault#additional-vault-acl-policies-for-sensitive-operations). ### JSON Request Body Schema @@ -182,7 +182,7 @@ The corresponding CLI command is [`consul connect ca set-config`](/commands/conn - `Config` `(map[string]string: )` - The raw configuration to use for the chosen provider. For more information on configuring the Connect CA - providers, see [Provider Config](/docs/connect/ca). + providers, see [Provider Config](/consul/docs/connect/ca). - `ForceWithoutCrossSigning` `(bool: false)` - Indicates that the CA change should be forced to complete even if the current CA doesn't support root cross-signing. @@ -191,7 +191,7 @@ The corresponding CLI command is [`consul connect ca set-config`](/commands/conn until service mesh proxies and/or Consul client agents receive a new certificate that establishes trust with the new root. Do not use this field unless you are sure you need it. - Refer to [Forced Rotation Without Cross-Signing](/docs/connect/ca#forced-rotation-without-cross-signing) + Refer to [Forced Rotation Without Cross-Signing](/consul/docs/connect/ca#forced-rotation-without-cross-signing) for more detail. ### Sample Payload diff --git a/website/content/api-docs/connect/index.mdx b/website/content/api-docs/connect/index.mdx index 4c5d209aaf..3324ec14e7 100644 --- a/website/content/api-docs/connect/index.mdx +++ b/website/content/api-docs/connect/index.mdx @@ -9,11 +9,11 @@ description: >- # Connect HTTP Endpoint The `/connect` endpoints provide access to -[Connect-related](/docs/connect) operations for +[Connect-related](/consul/docs/connect) operations for intentions and the certificate authority. There are also Connect-related endpoints in the -[Agent](/api-docs/agent) and [Catalog](/api-docs/catalog) APIs. For example, +[Agent](/consul/api-docs/agent) and [Catalog](/consul/api-docs/catalog) APIs. For example, the API for requesting a TLS certificate for a service is part of the agent APIs. And the catalog API has an endpoint for finding all Connect-capable services in the catalog. diff --git a/website/content/api-docs/connect/intentions.mdx b/website/content/api-docs/connect/intentions.mdx index a979a3e6d7..870b6d4b77 100644 --- a/website/content/api-docs/connect/intentions.mdx +++ b/website/content/api-docs/connect/intentions.mdx @@ -9,11 +9,11 @@ description: |- # Intentions - Connect HTTP API The `/connect/intentions` endpoint provide tools for managing -[intentions](/docs/connect/intentions). +[intentions](/consul/docs/connect/intentions). -> **1.9.0 and later:** Reading and writing intentions has been migrated to the -[`service-intentions`](/docs/connect/config-entries/service-intentions) +[`service-intentions`](/consul/docs/connect/config-entries/service-intentions) config entry kind. ## Upsert Intention by Name ((#upsert-intention-by-name)) @@ -36,10 +36,10 @@ be persisted using this endpoint and will require editing the enclosing | `PUT` | `/connect/intentions/exact` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------------ | @@ -54,19 +54,19 @@ The table below shows this endpoint's support for for more details.

-The corresponding CLI command is [`consul intention create -replace`](/commands/intention/create#replace). +The corresponding CLI command is [`consul intention create -replace`](/consul/commands/intention/create#replace). ### Query Parameters - `source` `(string: )` - Specifies the source service - according to the [source naming conventions](/commands/intention#source-and-destination-naming). + according to the [source naming conventions](/consul/commands/intention#source-and-destination-naming). - `destination` `(string: )` - Specifies the destination service - according to the [destination naming conventions](/commands/intention#source-and-destination-naming). + according to the [destination naming conventions](/consul/commands/intention#source-and-destination-naming). - `ns` `(string: "")` - Specifies the default namespace to use when `source` or `destination` query parameters do not include a namespace - as shown in the [source and destination naming conventions](/commands/intention#source-and-destination-naming). + as shown in the [source and destination naming conventions](/consul/commands/intention#source-and-destination-naming). You can also [specify the namespace through other methods](#methods-to-specify-namespace). ### JSON Request Body Schema @@ -83,7 +83,7 @@ The corresponding CLI command is [`consul intention create -replace`](/commands/ the `Permissions` field. - `Permissions` `(array)` - The list of all [additional L7 - attributes](/docs/connect/config-entries/service-intentions#intentionpermission) + attributes](/consul/docs/connect/config-entries/service-intentions#intentionpermission) that extend the intention match criteria. Permission precedence is applied top to bottom. For any given request the @@ -91,7 +91,7 @@ The corresponding CLI command is [`consul intention create -replace`](/commands/ evaluation. As with L4 intentions, traffic that fails to match any of the provided permissions in this intention will be subject to the default intention behavior is defined by the default [ACL - policy](/docs/agent/config/config-files#acl_default_policy). + policy](/consul/docs/agent/config/config-files#acl_default_policy). This should be omitted for an L4 intention as it is mutually exclusive with the `Action` field. @@ -127,7 +127,7 @@ true -> **Deprecated** - This endpoint is deprecated in Consul 1.9.0 in favor of [upserting by name](#upsert-intention-by-name) or editing the -[`service-intentions`](/docs/connect/config-entries/service-intentions) config +[`service-intentions`](/consul/docs/connect/config-entries/service-intentions) config entry for the destination. This endpoint creates a new intention and returns its ID if it was created @@ -142,10 +142,10 @@ existing intention or delete it prior to creating a new one. | `POST` | `/connect/intentions` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------------ | @@ -160,13 +160,13 @@ The table below shows this endpoint's support for for more details.

-The corresponding CLI command is [`consul intention create`](/commands/intention/create). +The corresponding CLI command is [`consul intention create`](/consul/commands/intention/create). ### Query Parameters - `ns` `(string: "")` - Specifies the default namespace to use when `SourceNS` or `DestinationNS` request body parameters do not include a namespace - as shown in the [source and destination naming conventions](/commands/intention#source-and-destination-naming). + as shown in the [source and destination naming conventions](/consul/commands/intention#source-and-destination-naming). You can also [specify the namespace through other methods](#methods-to-specify-namespace). ### JSON Request Body Schema @@ -229,7 +229,7 @@ $ curl \ -> **Deprecated** - This endpoint is deprecated in Consul 1.9.0 in favor of [upserting by name](#upsert-intention-by-name) or editing the -[`service-intentions`](/docs/connect/config-entries/service-intentions) config +[`service-intentions`](/consul/docs/connect/config-entries/service-intentions) config entry for the destination. This endpoint updates an intention with the given values. @@ -239,10 +239,10 @@ This endpoint updates an intention with the given values. | `PUT` | `/connect/intentions/:uuid` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------------ | @@ -293,10 +293,10 @@ This endpoint reads a specific intention by its unique source and destination. | `GET` | `/connect/intentions/exact` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ----------------------------- | @@ -311,19 +311,19 @@ The table below shows this endpoint's support for for more details.

-The corresponding CLI command is [`consul intention get`](/commands/intention/get). +The corresponding CLI command is [`consul intention get`](/consul/commands/intention/get). ### Query Parameters - `source` `(string: )` - Specifies the source service - according to the [source naming conventions](/commands/intention#source-and-destination-naming). + according to the [source naming conventions](/consul/commands/intention#source-and-destination-naming). - `destination` `(string: )` - Specifies the destination service - according to the [destination naming conventions](/commands/intention#source-and-destination-naming). + according to the [destination naming conventions](/consul/commands/intention#source-and-destination-naming). - `ns` `(string: "")` - Specifies the default namespace to use when `source` or `destination` query parameters do not include a namespace - as shown in the [source and destination naming conventions](/commands/intention#source-and-destination-naming). + as shown in the [source and destination naming conventions](/consul/commands/intention#source-and-destination-naming). You can also [specify the namespace through other methods](#methods-to-specify-namespace). ### Sample Request @@ -355,7 +355,7 @@ $ curl \ -> **Deprecated** - This endpoint is deprecated in Consul 1.9.0 in favor of [reading by name](#read-specific-intention-by-name) or by viewing the -[`service-intentions`](/docs/connect/config-entries/service-intentions) +[`service-intentions`](/consul/docs/connect/config-entries/service-intentions) config entry for the destination. This endpoint reads a specific intention. @@ -365,10 +365,10 @@ This endpoint reads a specific intention. | `GET` | `/connect/intentions/:uuid` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ----------------------------- | @@ -383,7 +383,7 @@ The table below shows this endpoint's support for for more details.

-The corresponding CLI command is [`consul intention get`](/commands/intention/get). +The corresponding CLI command is [`consul intention get`](/consul/commands/intention/get). ### Path Parameters @@ -428,10 +428,10 @@ This endpoint lists all intentions. | `GET` | `/connect/intentions` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ----------------------------- | @@ -446,7 +446,7 @@ The table below shows this endpoint's support for for more details.

-The corresponding CLI command is [`consul intention list`](/commands/intention/list). +The corresponding CLI command is [`consul intention list`](/consul/commands/intention/list). ### Query Parameters @@ -515,10 +515,10 @@ This endpoint deletes a specific intention by its unique source and destination. | `DELETE` | `/connect/intentions/exact` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------------ | @@ -533,19 +533,19 @@ The table below shows this endpoint's support for for more details.

-The corresponding CLI command is [`consul intention delete`](/commands/intention/delete). +The corresponding CLI command is [`consul intention delete`](/consul/commands/intention/delete). ### Query Parameters - `source` `(string: )` - Specifies the source service - according to the [source naming conventions](/commands/intention#source-and-destination-naming). + according to the [source naming conventions](/consul/commands/intention#source-and-destination-naming). - `destination` `(string: )` - Specifies the destination service - according to the [destination naming conventions](/commands/intention#source-and-destination-naming). + according to the [destination naming conventions](/consul/commands/intention#source-and-destination-naming). - `ns` `(string: "")` - Specifies the default namespace to use when `source` or `destination` query parameters do not include a namespace - as shown in the [source and destination naming conventions](/commands/intention#source-and-destination-naming). + as shown in the [source and destination naming conventions](/consul/commands/intention#source-and-destination-naming). You can also [specify the namespace through other methods](#methods-to-specify-namespace). ### Sample Request @@ -560,7 +560,7 @@ $ curl \ -> **Deprecated** - This endpoint is deprecated in Consul 1.9.0 in favor of [deleting by name](#delete-intention-by-name) or editing the -[`service-intentions`](/docs/connect/config-entries/service-intentions) config +[`service-intentions`](/consul/docs/connect/config-entries/service-intentions) config entry for the destination. This endpoint deletes a specific intention. @@ -570,10 +570,10 @@ This endpoint deletes a specific intention. | `DELETE` | `/connect/intentions/:uuid` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------------ | @@ -588,7 +588,7 @@ The table below shows this endpoint's support for for more details.

-The corresponding CLI command is [`consul intention delete`](/commands/intention/delete). +The corresponding CLI command is [`consul intention delete`](/consul/commands/intention/delete). ### Path Parameters @@ -614,7 +614,7 @@ networking layer 4 (e.g. TCP) integration. For performance and reliability reasons it is desirable to implement intention enforcement by listing [intentions that match the -destination](/api-docs/connect/intentions#list-matching-intentions) and representing +destination](/consul/api-docs/connect/intentions#list-matching-intentions) and representing them in the native configuration of the proxy itself (such as RBAC for Envoy). This endpoint will work even if the destination service has @@ -626,10 +626,10 @@ does not contain any information about the intention itself. | `GET` | `/connect/intentions/check` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ----------------------------- | @@ -644,19 +644,19 @@ The table below shows this endpoint's support for for more details.

-The corresponding CLI command is [`consul intention check`](/commands/intention/check). +The corresponding CLI command is [`consul intention check`](/consul/commands/intention/check). ### Query Parameters - `source` `(string: )` - Specifies the source service - according to the [source naming conventions](/commands/intention#source-and-destination-naming). + according to the [source naming conventions](/consul/commands/intention#source-and-destination-naming). - `destination` `(string: )` - Specifies the destination service - according to the [destination naming conventions](/commands/intention#source-and-destination-naming). + according to the [destination naming conventions](/consul/commands/intention#source-and-destination-naming). - `ns` `(string: "")` - Specifies the default namespace to use when `source` or `destination` query parameters do not include a namespace - as shown in the [source and destination naming conventions](/commands/intention#source-and-destination-naming). + as shown in the [source and destination naming conventions](/consul/commands/intention#source-and-destination-naming). You can also [specify the namespace through other methods](#methods-to-specify-namespace). ### Sample Request @@ -686,10 +686,10 @@ The intentions in the response are in evaluation order. | `GET` | `/connect/intentions/match` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | -------------------- | ----------------------------- | @@ -704,7 +704,7 @@ The table below shows this endpoint's support for for more details.

-The corresponding CLI command is [`consul intention match`](/commands/intention/match). +The corresponding CLI command is [`consul intention match`](/consul/commands/intention/match). ### Query Parameters @@ -712,12 +712,12 @@ The corresponding CLI command is [`consul intention match`](/commands/intention/ by "source" or "destination". - `name` `(string: )` - Specifies a name to match - according to the [source and destination naming conventions](/commands/intention#source-and-destination-naming). + according to the [source and destination naming conventions](/consul/commands/intention#source-and-destination-naming). You can repeat this parameter for batching multiple matches. - `ns` `(string: "")` - Specifies the default namespace to use when the `name` query parameter does not include a namespace - as shown in the [source and destination naming conventions](/commands/intention#source-and-destination-naming). + as shown in the [source and destination naming conventions](/consul/commands/intention#source-and-destination-naming). You can also [specify the namespace through other methods](#methods-to-specify-namespace). ### Sample Request diff --git a/website/content/api-docs/coordinate.mdx b/website/content/api-docs/coordinate.mdx index 2116569f2e..ab00205e6e 100644 --- a/website/content/api-docs/coordinate.mdx +++ b/website/content/api-docs/coordinate.mdx @@ -13,7 +13,7 @@ The `/coordinate` endpoints query for the network coordinates for nodes in the local datacenter as well as Consul servers in the local datacenter and remote datacenters. -Please see the [Network Coordinates](/docs/architecture/coordinates) internals +Please see the [Network Coordinates](/consul/docs/architecture/coordinates) internals guide for more information on how these coordinates are computed, and for details on how to perform calculations with them. @@ -29,16 +29,16 @@ cluster. | `GET` | `/coordinate/datacenters` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `none` | -The corresponding CLI command is [`consul rtt -wan`](/commands/rtt#wan). +The corresponding CLI command is [`consul rtt -wan`](/consul/commands/rtt#wan). ### Sample Request @@ -85,16 +85,16 @@ datacenter. | `GET` | `/coordinate/nodes` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `YES` | `all` | `none` | `node:read` | -The corresponding CLI command is [`consul rtt`](/commands/rtt). +The corresponding CLI command is [`consul rtt`](/consul/commands/rtt). ### Query Parameters @@ -144,10 +144,10 @@ This endpoint returns the LAN network coordinates for the given node. | `GET` | `/coordinate/node/:node_name` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | @@ -206,10 +206,10 @@ datacenter. | `PUT` | `/coordinate/update` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | diff --git a/website/content/api-docs/discovery-chain.mdx b/website/content/api-docs/discovery-chain.mdx index c501d5d9a6..a96f0e89fe 100644 --- a/website/content/api-docs/discovery-chain.mdx +++ b/website/content/api-docs/discovery-chain.mdx @@ -9,17 +9,17 @@ description: The /discovery-chain endpoints are for interacting with the discove -> **1.6.0+:** The discovery chain API is available in Consul versions 1.6.0 and newer. ~> This is a low-level API primarily targeted at developers building external -[Connect proxy integrations](/docs/connect/proxies/integrate). Future +[Connect proxy integrations](/consul/docs/connect/proxies/integrate). Future high-level proxy integration APIs may obviate the need for this API over time. The `/discovery-chain` endpoint returns the compiled [discovery -chain](/docs/connect/l7-traffic/discovery-chain) for a service. +chain](/consul/docs/connect/l7-traffic/discovery-chain) for a service. This will fetch all related [configuration -entries](/docs/agent/config-entries) and render them into a form suitable -for use by a [connect proxy](/docs/connect/proxies) implementation. This +entries](/consul/docs/agent/config-entries) and render them into a form suitable +for use by a [connect proxy](/consul/docs/connect/proxies) implementation. This is a key component of [L7 Traffic -Management](/docs/connect/l7-traffic). +Management](/consul/docs/connect/l7-traffic). ## Read Compiled Discovery Chain @@ -38,10 +38,10 @@ the `POST` method must be used, otherwise `GET` is sufficient.

The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | -------------------- | -------------- | @@ -58,8 +58,8 @@ The table below shows this endpoint's support for compilation. This will default to the datacenter of the agent being queried. This value comes from an [upstream - configuration](/docs/connect/registration/service-registration#upstream-configuration-reference) - [`datacenter`](/docs/connect/registration/service-registration#datacenter) + configuration](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) + [`datacenter`](/consul/docs/connect/registration/service-registration#datacenter) parameter. - `ns` `(string: "")` - Specifies the source namespace you use as the basis of compilation. @@ -68,17 +68,17 @@ The table below shows this endpoint's support for ### JSON Request Body Schema - `OverrideConnectTimeout` `(duration: 0s)` - Overrides the final [connect - timeout](/docs/connect/config-entries/service-resolver#connecttimeout) for + timeout](/consul/docs/connect/config-entries/service-resolver#connecttimeout) for any service resolved in the compiled chain. This value comes from the `connect_timeout_ms` key in an [upstream - configuration](/docs/connect/registration/service-registration#upstream-configuration-reference) + configuration](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) opaque - [`config`](/docs/connect/registration/service-registration#config-1) + [`config`](/consul/docs/connect/registration/service-registration#config-1) parameter. - `OverrideProtocol` `(string: "")` - Overrides the final - [protocol](/docs/connect/config-entries/service-defaults#protocol) used in + [protocol](/consul/docs/connect/config-entries/service-defaults#protocol) used in the compiled discovery chain. If the chain ordinarily would be TCP and an L7 protocol is passed here the @@ -87,21 +87,21 @@ The table below shows this endpoint's support for Splitters. This value comes from the `protocol` key in an [upstream - configuration](/docs/connect/registration/service-registration#upstream-configuration-reference) + configuration](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) opaque - [`config`](/docs/connect/registration/service-registration#config-1) + [`config`](/consul/docs/connect/registration/service-registration#config-1) parameter. - `OverrideMeshGateway` `(MeshGatewayConfig: )` - Overrides the final - [mesh gateway configuration](/docs/connect/gateways/mesh-gateway#connect-proxy-configuration) + [mesh gateway configuration](/consul/docs/connect/gateways/mesh-gateway#connect-proxy-configuration) for this any service resolved in the compiled chain. This value comes from either the [proxy - configuration](/docs/connect/registration/service-registration#complete-configuration-example) - [`mesh_gateway`](/docs/connect/registration/service-registration#mesh_gateway) + configuration](/consul/docs/connect/registration/service-registration#complete-configuration-example) + [`mesh_gateway`](/consul/docs/connect/registration/service-registration#mesh_gateway) parameter or an [upstream - configuration](/docs/connect/registration/service-registration#upstream-configuration-reference) - [`mesh_gateway`](/docs/connect/registration/service-registration#mesh_gateway-1) + configuration](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) + [`mesh_gateway`](/consul/docs/connect/registration/service-registration#mesh_gateway-1) parameter. If both are present the value defined on the upstream is used. - `Mode` `(string: "")` - One of `none`, `local`, or `remote`. @@ -109,7 +109,7 @@ The table below shows this endpoint's support for ### Sample Compilations Full documentation for the output fields is found on the [discovery chain -internals](/docs/connect/l7-traffic/discovery-chain#compileddiscoverychain) +internals](/consul/docs/connect/l7-traffic/discovery-chain#compileddiscoverychain) page. #### Multi-Datacenter Failover diff --git a/website/content/api-docs/event.mdx b/website/content/api-docs/event.mdx index ac13d0ddda..2e283fc460 100644 --- a/website/content/api-docs/event.mdx +++ b/website/content/api-docs/event.mdx @@ -20,16 +20,16 @@ This endpoint triggers a new user event. | `PUT` | `/event/fire/:name` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------- | | `NO` | `none` | `none` | `event:write` | -The corresponding CLI command is [`consul event`](/commands/event). +The corresponding CLI command is [`consul event`](/consul/commands/event). ### Path Parameters @@ -86,9 +86,9 @@ $ curl \ ## List Events This endpoint returns the most recent events (up to 256) known by the agent. As a -consequence of how the [event command](/commands/event) works, each +consequence of how the [event command](/consul/commands/event) works, each agent may have a different view of the events. Events are broadcast using the -[gossip protocol](/docs/architecture/gossip), so they have no global ordering +[gossip protocol](/consul/docs/architecture/gossip), so they have no global ordering nor do they make a promise of delivery. @include 'http_api_results_filtered_by_acls.mdx' @@ -98,10 +98,10 @@ nor do they make a promise of delivery. | `GET` | `/event/list` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | @@ -146,7 +146,7 @@ $ curl \ The semantics of this endpoint's blocking queries are slightly different. Most blocking queries provide a monotonic index and block until a newer index is available. This can be supported as a consequence of the total ordering of the -[consensus protocol](/docs/architecture/consensus). With gossip, there is no +[consensus protocol](/consul/docs/architecture/consensus). With gossip, there is no ordering, and instead `X-Consul-Index` maps to the newest event that matches the query. diff --git a/website/content/api-docs/features/consistency.mdx b/website/content/api-docs/features/consistency.mdx index 692b2e1fb0..bcd7d621d6 100644 --- a/website/content/api-docs/features/consistency.mdx +++ b/website/content/api-docs/features/consistency.mdx @@ -22,7 +22,7 @@ to fine-tune these trade-offs for their own use case at two levels: Consul servers are responsible for maintaining state information like the registration and health status of services and nodes. To protect this state against the potential failure of Consul servers, this state is replicated across three or more Consul servers in production using a -[consensus protocol](/docs/architecture/consensus). +[consensus protocol](/consul/docs/architecture/consensus). One Consul server is elected leader and acts as the ultimate authority on Consul's state. If a majority of Consul servers agree to a state change, the leader is responsible for recording @@ -74,8 +74,8 @@ Each HTTP API endpoint documents its support for the three read consistency mode ~> **Scaling read requests**: The most effective way to increase read scalability is to convert non-`stale` reads to `stale` reads. If most requests are already `stale` reads and additional load reduction is desired, use Consul Enterprise -[redundancy zones](/docs/enterprise/redundancy) or -[read replicas](/docs/enterprise/read-scale) +[redundancy zones](/consul/docs/enterprise/redundancy) or +[read replicas](/consul/docs/enterprise/read-scale) to spread `stale` reads across additional, _non-voting_ Consul servers. Non-voting servers enhance read scalability without increasing the number of voting servers; adding more then 5 voting servers is not recommended because @@ -111,7 +111,7 @@ When making a request across federated Consul datacenters, requests are forwarde a local server to any remote server. Once in the remote datacenter, the request path is the same as a [local request with the same consistency mode](#intra-datacenter-request-behavior). The following diagrams show the cross-datacenter request paths when Consul servers in datacenters are -[federated either directly or via mesh gateways](/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways). +[federated either directly or via mesh gateways](/consul/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways). @@ -131,10 +131,10 @@ The following diagrams show the cross-datacenter request paths when Consul serve ### Consul DNS Queries -When DNS queries are issued to [Consul's DNS interface](/docs/discovery/dns), +When DNS queries are issued to [Consul's DNS interface](/consul/docs/discovery/dns), Consul uses the `stale` consistency mode by default when interfacing with its underlying Consul service discovery HTTP APIs -([Catalog](/api-docs/catalog), [Health](/api-docs/health), and [Prepared Query](/api-docs/query)). +([Catalog](/consul/api-docs/catalog), [Health](/consul/api-docs/health), and [Prepared Query](/consul/api-docs/query)). The consistency mode underlying Consul DNS queries cannot be overridden on a per-request basis. @@ -203,9 +203,9 @@ when calling the endpoint: The default consistency mode can be changed to `stale` for service discovery HTTP API endpoints, including: -- [Catalog API](/api-docs/catalog) -- [Health API](/api-docs/health) -- [Prepared Query API](/api-docs/query) +- [Catalog API](/consul/api-docs/catalog) +- [Health API](/consul/api-docs/health) +- [Prepared Query API](/consul/api-docs/query) This allows Consul operators to spread service discovery read load across Consul servers with a centralized configuration change, avoiding the need to modify every service to @@ -270,9 +270,9 @@ The DNS interface does not support viewing the consistency mode used for a parti Note that some HTTP API endpoints support a `cached` parameter which has some of the same semantics as `stale` consistency mode but different trade offs. This behavior is described in -[agent caching feature documentation](/api-docs/features/caching) +[agent caching feature documentation](/consul/api-docs/features/caching) -[`dns_config.allow_stale`]: /docs/agent/config/config-files#allow_stale -[`dns_config.max_stale`]: /docs/agent/config/config-files#max_stale -[`discovery_max_stale`]: /docs/agent/config/config-files#discovery_max_stale +[`dns_config.allow_stale`]: /consul/docs/agent/config/config-files#allow_stale +[`dns_config.max_stale`]: /consul/docs/agent/config/config-files#max_stale +[`discovery_max_stale`]: /consul/docs/agent/config/config-files#discovery_max_stale diff --git a/website/content/api-docs/features/filtering.mdx b/website/content/api-docs/features/filtering.mdx index b4a25b242c..427bf9210f 100644 --- a/website/content/api-docs/features/filtering.mdx +++ b/website/content/api-docs/features/filtering.mdx @@ -122,7 +122,7 @@ example, the following two expressions would be equivalent. Generally, only the main object is filtered. When filtering for an item within an array that is not at the top level, the entire array that contains the item will be returned. This is usually the outermost object of a response, -but in some cases such the [`/catalog/node/:node`](/api-docs/catalog#list-services-for-node) +but in some cases such the [`/catalog/node/:node`](/consul/api-docs/catalog#list-services-for-node) endpoint the filtering is performed on a object embedded within the results. ### Performance diff --git a/website/content/api-docs/health.mdx b/website/content/api-docs/health.mdx index ba5eef9788..645381a209 100644 --- a/website/content/api-docs/health.mdx +++ b/website/content/api-docs/health.mdx @@ -15,7 +15,7 @@ from the health endpoints are filtered while the catalog endpoints provide the raw entries. To modify health check registration or information, -use the [`/agent/check`](/api-docs/agent/check) endpoints. +use the [`/agent/check`](/consul/api-docs/agent/check) endpoints. ## List Checks for Node @@ -28,10 +28,10 @@ This endpoint returns the checks specific to the node provided on the path. | `GET` | `/health/node/:node` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------ | @@ -122,10 +122,10 @@ path. | `GET` | `/health/checks/:service` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------ | @@ -212,10 +212,10 @@ incorporating the use of health checks. | `GET` | `/health/service/:service` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | -------------------- | ----------------- | -------------------- | ------------------------ | @@ -239,7 +239,7 @@ The table below shows this endpoint's support for ascending order based on the estimated round trip time from that node. Passing `?near=_agent` uses the agent's node for the sort. ~> **Note:** Using `near` will ignore - [`use_streaming_backend`](/docs/agent/config/config-files#use_streaming_backend) and always + [`use_streaming_backend`](/consul/docs/agent/config/config-files#use_streaming_backend) and always use blocking queries, because the data required to sort the results is not available to the streaming backend. @@ -266,10 +266,10 @@ The table below shows this endpoint's support for - `merge-central-config` - Include this flag in a request for `connect-proxy` kind or `*-gateway` kind services to return a fully resolved service definition that includes merged values from the - [proxy-defaults/global](/docs/connect/config-entries/proxy-defaults) and - [service-defaults/:service](/docs/connect/config-entries/service-defaults) config entries. + [proxy-defaults/global](/consul/docs/connect/config-entries/proxy-defaults) and + [service-defaults/:service](/consul/docs/connect/config-entries/service-defaults) config entries. Returning a fully resolved service definition is useful when a service was registered using the - [/catalog/register](/api-docs/catalog#register_entity) endpoint, which does not automatically merge config entries. + [/catalog/register](/consul/api-docs/catalog#register_entity) endpoint, which does not automatically merge config entries. - `ns` `(string: "")` - Specifies the namespace of the service. You can also [specify the namespace through other methods](#methods-to-specify-namespace). @@ -413,7 +413,7 @@ following selectors and filter operations being supported: ## List Service Instances for Connect-enabled Service This endpoint returns the service instances providing a -[Connect-capable](/docs/connect) service in a given datacenter. +[Connect-capable](/consul/docs/connect) service in a given datacenter. This will include both proxies and native integrations. A service may register both Connect-capable and incapable services at the same time, so this endpoint may be used to filter only the Connect-capable endpoints. @@ -425,14 +425,14 @@ so this endpoint may be used to filter only the Connect-capable endpoints. | `GET` | `/health/connect/:service` | `application/json` | Parameters and response format are the same as -[`/health/service/:service`](/api-docs/health#list-nodes-for-service). +[`/health/service/:service`](/consul/api-docs/health#list-nodes-for-service). ## List Service Instances for Ingress Gateways Associated with a Service -> **1.8.0+:** This API is available in Consul versions 1.8.0 and later. This endpoint returns the service instances providing an [ingress -gateway](/docs/connect/gateways/ingress-gateway) for a service in a given datacenter. +gateway](/consul/docs/connect/gateways/ingress-gateway) for a service in a given datacenter. @include 'http_api_results_filtered_by_acls.mdx' @@ -441,10 +441,10 @@ gateway](/docs/connect/gateways/ingress-gateway) for a service in a given datace | `GET` | `/health/ingress/:service` | `application/json` | Parameters and response format are the same as -[`/health/service/:service`](/api-docs/health#list-nodes-for-service). +[`/health/service/:service`](/consul/api-docs/health#list-nodes-for-service). ~> **Note:** Unlike `/health/connect/:service` and `/health/service/:service` this -endpoint does not support the `peer` query parameter and the [streaming backend](/api-docs/features/blocking#streaming-backend). +endpoint does not support the `peer` query parameter and the [streaming backend](/consul/api-docs/features/blocking#streaming-backend). ## List Checks in State @@ -457,10 +457,10 @@ This endpoint returns the checks in the state provided on the path. | `GET` | `/health/state/:state` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------ | diff --git a/website/content/api-docs/index.mdx b/website/content/api-docs/index.mdx index 4d16ef5128..20d0021e30 100644 --- a/website/content/api-docs/index.mdx +++ b/website/content/api-docs/index.mdx @@ -7,53 +7,53 @@ description: |- # Consul API Overview -The Consul HTTP API is a RESTful interface that allows you to leverage Consul functionality in your network. This topic provides guidance about the essential API endpoints for different workstreams. Refer to the [HTTP API structure](/api-docs/api-structure) docs to learn how to interact with and authenticate against the Consul HTTP API. +The Consul HTTP API is a RESTful interface that allows you to leverage Consul functionality in your network. This topic provides guidance about the essential API endpoints for different workstreams. Refer to the [HTTP API structure](/consul/api-docs/api-structure) docs to learn how to interact with and authenticate against the Consul HTTP API. ## Connect your services Use the following API endpoints to configure and connect your services. -- [`/catalog`](/api-docs/catalog): Register and deregister nodes, services, and health checks. -- [`/health`](/api-docs/health): Query node health when health checks are enabled. -- [`/query`](/api-docs/query): Create and manage prepared queries in Consul. Prepared queries allow you to register a complex service query and send it later. -- [`/coordinate`](/api-docs/coordinate): Query the network coordinates for nodes in the local datacenter and Consul servers in the local datacenter and remote datacenters. +- [`/catalog`](/consul/api-docs/catalog): Register and deregister nodes, services, and health checks. +- [`/health`](/consul/api-docs/health): Query node health when health checks are enabled. +- [`/query`](/consul/api-docs/query): Create and manage prepared queries in Consul. Prepared queries allow you to register a complex service query and send it later. +- [`/coordinate`](/consul/api-docs/coordinate): Query the network coordinates for nodes in the local datacenter and Consul servers in the local datacenter and remote datacenters. The following endpoints are specific to service mesh: -- [`/config`](/api-docs/config): Create, update, delete, and query central configuration entries registered with Consul. Configuration entries define the default behavior of resources in the service mesh. -- [`/agent/connect`](/api-docs/agent/connect): Interact with local agents in the service mesh. -- [`/connect`](/api-docs/connect): Manage service mesh-related operations, including service intentions ([`/connect/intentions`](/api-docs/connect/intentions)) and the service mesh certificate authority (CA) ([`/connect/ca`](/api-docs/connect/ca)). +- [`/config`](/consul/api-docs/config): Create, update, delete, and query central configuration entries registered with Consul. Configuration entries define the default behavior of resources in the service mesh. +- [`/agent/connect`](/consul/api-docs/agent/connect): Interact with local agents in the service mesh. +- [`/connect`](/consul/api-docs/connect): Manage service mesh-related operations, including service intentions ([`/connect/intentions`](/consul/api-docs/connect/intentions)) and the service mesh certificate authority (CA) ([`/connect/ca`](/consul/api-docs/connect/ca)). ## Enable zero-trust network security The following API endpoints give you control over access to services in your network and access to the Consul API. -- [`/acl`](/api-docs/acl): Create and manage tokens that authenticate requests and authorize access to resources in the network. We recommend enabling access control lists (ACL) to secure access to the Consul API, UI, and CLI. -- [`/connect/intentions`](/api-docs/connect/intentions): Create and manage service intentions. +- [`/acl`](/consul/api-docs/acl): Create and manage tokens that authenticate requests and authorize access to resources in the network. We recommend enabling access control lists (ACL) to secure access to the Consul API, UI, and CLI. +- [`/connect/intentions`](/consul/api-docs/connect/intentions): Create and manage service intentions. ## Observe your network Use the following API endpoints enable network observability. -- [`/status`](/api-docs/status): Debug your Consul datacenter by returning low-level Raft information about Consul server peers. -- [`/agent/metrics`](/api-docs/agent#view-metrics): Retrieve metrics for the most recent intervals that have finished. For more information about metrics, refer to [Telemetry](/docs/agent/telemetry). +- [`/status`](/consul/api-docs/status): Debug your Consul datacenter by returning low-level Raft information about Consul server peers. +- [`/agent/metrics`](/consul/api-docs/agent#view-metrics): Retrieve metrics for the most recent intervals that have finished. For more information about metrics, refer to [Telemetry](/consul/docs/agent/telemetry). ## Manage Consul The following API endpoints help you manage Consul operations. -- [`/operator`](/api-docs/operator): Perform cluster-level tasks, such as interacting with the Raft subsystem or obtaining license information. -- [`/partition`](/api-docs/admin-partitions): Create and manage administrative or admin partitions in Consul. Admin partitions are supersets of Consul namespaces that isolate groups of resources to lower operational overhead. -- [`/namespace`](/api-docs/namespaces): Create and manage namespaces in Consul. Namespaces isolate groups of resources to lower operational overhead. -- [`/snapshot`](/api-docs/snapshot): Save and restore Consul server state in the event of a disaster. -- [`/txn`](/api-docs/txn): Apply multiple operations, such as updating the catalog and retrieving multiple KV entries, in a single transaction. +- [`/operator`](/consul/api-docs/operator): Perform cluster-level tasks, such as interacting with the Raft subsystem or obtaining license information. +- [`/partition`](/consul/api-docs/admin-partitions): Create and manage administrative or admin partitions in Consul. Admin partitions are supersets of Consul namespaces that isolate groups of resources to lower operational overhead. +- [`/namespace`](/consul/api-docs/namespaces): Create and manage namespaces in Consul. Namespaces isolate groups of resources to lower operational overhead. +- [`/snapshot`](/consul/api-docs/snapshot): Save and restore Consul server state in the event of a disaster. +- [`/txn`](/consul/api-docs/txn): Apply multiple operations, such as updating the catalog and retrieving multiple KV entries, in a single transaction. ## Configure your services dynamically The following API endpoints enable you to dynamically configure your services. -- [`/event`](/api-docs/event): Start a custom event that you can use to build scripts and automations. -- [`/kv`](/api-docs/kv): Add, remove, and update metadata stored in the Consul KV store. -- [`/session`](/api-docs/session): Create and manage [sessions](/docs/dynamic-app-config/sessions) in Consul. You can use sessions to build distributed and granular locks to ensure nodes are properly writing to the Consul KV store. +- [`/event`](/consul/api-docs/event): Start a custom event that you can use to build scripts and automations. +- [`/kv`](/consul/api-docs/kv): Add, remove, and update metadata stored in the Consul KV store. +- [`/session`](/consul/api-docs/session): Create and manage [sessions](/consul/docs/dynamic-app-config/sessions) in Consul. You can use sessions to build distributed and granular locks to ensure nodes are properly writing to the Consul KV store. diff --git a/website/content/api-docs/kv.mdx b/website/content/api-docs/kv.mdx index f23306403d..9f449e5d0a 100644 --- a/website/content/api-docs/kv.mdx +++ b/website/content/api-docs/kv.mdx @@ -19,7 +19,7 @@ replication between datacenters, please view the ~> Values in the KV store cannot be larger than 512kb. In order to perform atomic operations on multiple KV pairs (up to a limit of 64) -please consider using [transactions](/api-docs/txn) instead. +please consider using [transactions](/consul/api-docs/txn) instead. ## Read Key @@ -27,29 +27,29 @@ This endpoint returns the specified key. If no key exists at the given path, a 404 is returned instead of a 200 response. For multi-key reads (up to a limit of 64 KV operations) please consider using -[transactions](/api-docs/txn) instead. +[transactions](/consul/api-docs/txn) instead. If the [`recurse`](#recurse) or [`keys`](#keys) query parameters are `true`, this endpoint will return an array of keys. In this case, the HTTP response includes the `X-Consul-Results-Filtered-By-ACLs: true` header if the response array excludes results due to ACL policy configuration. -Refer to the [HTTP API documentation](/api-docs/api-structure#results-filtered-by-acls) for more information. +Refer to the [HTTP API documentation](/consul/api-docs/api-structure#results-filtered-by-acls) for more information. | Method | Path | Produces | | ------ | ---------- | ------------------ | | `GET` | `/kv/:key` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `YES` | `all` | `none` | `key:read` | -The corresponding CLI command is [`consul kv get`](/commands/kv/get). +The corresponding CLI command is [`consul kv get`](/consul/commands/kv/get). ### Path Parameters @@ -168,16 +168,16 @@ Even though the return type is `application/json`, the value is either `true` or `false`, indicating whether the create/update succeeded. The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `key:write` | -The corresponding CLI command is [`consul kv put`](/commands/kv/put). +The corresponding CLI command is [`consul kv put`](/consul/commands/kv/put). ### Path Parameters @@ -210,7 +210,7 @@ The corresponding CLI command is [`consul kv put`](/commands/kv/put). session has locked the key.** For an example of how to use the lock feature, check the - [Leader Election tutorial](https://learn.hashicorp.com/tutorials/consul/application-leader-elections). + [Leader Election tutorial](/consul/tutorials/developer-configuration/application-leader-elections). - `release` `(string: "")` - Supply a session ID to use in a release operation. This is useful when paired with `?acquire=` as it allows clients to yield a lock. This @@ -255,16 +255,16 @@ This endpoint deletes a single key or all keys sharing a prefix. | `DELETE` | `/kv/:key` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `key:write` | -The corresponding CLI command is [`consul kv delete`](/commands/kv/delete). +The corresponding CLI command is [`consul kv delete`](/consul/commands/kv/delete). ### Path Parameters diff --git a/website/content/api-docs/namespaces.mdx b/website/content/api-docs/namespaces.mdx index beeaf84af3..2dd41a7e9b 100644 --- a/website/content/api-docs/namespaces.mdx +++ b/website/content/api-docs/namespaces.mdx @@ -20,16 +20,16 @@ This endpoint creates a new Namespace. | `PUT` | `/namespace` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ---------------- | | `NO` | `none` | `none` | `operator:write` | -The corresponding CLI command is [`consul namespace create`](/commands/namespace/create). +The corresponding CLI command is [`consul namespace create`](/consul/commands/namespace/create). ### JSON Request Body Schema @@ -53,7 +53,7 @@ The corresponding CLI command is [`consul namespace create`](/commands/namespace struct is an object with an "ID" and/or "Name" field to identify a policy. When a name is used instead of an ID, Consul will resolve the name to an ID and store that internally. The ACL token used in the API request - must have [`acl:write` access](/docs/security/acl/acl-rules#acl-resource-rules) + must have [`acl:write` access](/consul/docs/security/acl/acl-rules#acl-resource-rules) to the linked policy. - `RoleDefaults` `(array)` - This is the list of default roles @@ -61,7 +61,7 @@ The corresponding CLI command is [`consul namespace create`](/commands/namespace struct is an object with an "ID" and/or "Name" field to identify a policy. When a name is used instead of an ID, Consul will resolve the name to an ID and store that internally. The ACL token used in the API request - must have [`acl:write` access](/docs/security/acl/acl-rules#acl-resource-rules) + must have [`acl:write` access](/consul/docs/security/acl/acl-rules#acl-resource-rules) access to the linked role. - `Meta` `(map: )` - Specifies arbitrary KV metadata @@ -151,10 +151,10 @@ This endpoint reads a Namespace with the given name. | `GET` | `/namespace/:name` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------------------------------- | @@ -163,7 +163,7 @@ The table below shows this endpoint's support for 1 Access can be granted to list the Namespace if the token used when making the request has been granted any access in the namespace (read, list or write). -The corresponding CLI command is [`consul namespace read`](/commands/namespace/read). +The corresponding CLI command is [`consul namespace read`](/consul/commands/namespace/read). ### Path Parameters @@ -221,16 +221,16 @@ This endpoint updates a Namespace. | `PUT` | `/namespace/:name` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ---------------- | | `NO` | `none` | `none` | `operator:write` | -The corresponding CLI command is [`consul namespace update`](/commands/namespace/update) or [`consul namespace write`](/commands/namespace/write). +The corresponding CLI command is [`consul namespace update`](/consul/commands/namespace/update) or [`consul namespace write`](/consul/commands/namespace/write). ### Path Parameters @@ -258,7 +258,7 @@ The corresponding CLI command is [`consul namespace update`](/commands/namespace struct is an object with an "ID" and/or "Name" field to identify a policy. When a name is used instead of an ID, Consul will resolve the name to an ID and store that internally. The ACL token used in the API request - must have [`acl:write` access](/docs/security/acl/acl-rules#acl-resource-rules) + must have [`acl:write` access](/consul/docs/security/acl/acl-rules#acl-resource-rules) to the linked policy. - `RoleDefaults` `(array)` - This is the list of default roles @@ -266,7 +266,7 @@ The corresponding CLI command is [`consul namespace update`](/commands/namespace struct is an object with an "ID" and/or "Name" field to identify a policy. When a name is used instead of an ID, Consul will resolve the name to an ID and store that internally. The ACL token used in the API request - must have [`acl:write` access](/docs/security/acl/acl-rules#acl-resource-rules) + must have [`acl:write` access](/consul/docs/security/acl/acl-rules#acl-resource-rules) to the linked role. - `Meta` `(map: )` - Specifies arbitrary KV metadata @@ -363,16 +363,16 @@ This endpoint will return no data. Success or failure is indicated by the status code returned. The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ---------------- | | `NO` | `none` | `none` | `operator:write` | -The corresponding CLI command is [`consul namespace delete`](/commands/namespace/delete). +The corresponding CLI command is [`consul namespace delete`](/consul/commands/namespace/delete). ### Path Parameters @@ -435,10 +435,10 @@ privileges of the ACL token used for the request. | `GET` | `/namespaces` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------------------------------------------- | @@ -447,7 +447,7 @@ The table below shows this endpoint's support for 1 Access can be granted to list the Namespace if the token used when making the request has been granted any access in the namespace (read, list or write). -The corresponding CLI command is [`consul namespace list`](/commands/namespace/list). +The corresponding CLI command is [`consul namespace list`](/consul/commands/namespace/list). ### Sample Request diff --git a/website/content/api-docs/operator/area.mdx b/website/content/api-docs/operator/area.mdx index 3a0aef119c..2c1b968d5e 100644 --- a/website/content/api-docs/operator/area.mdx +++ b/website/content/api-docs/operator/area.mdx @@ -24,7 +24,7 @@ datacenters, so not all servers need to be fully connected. This allows for complex topologies among Consul datacenters like hub/spoke and more general trees. -Please check the [Network Areas tutorial](https://learn.hashicorp.com/tutorials/consul/federation-network-areas) for more details. +Please check the [Network Areas tutorial](/consul/tutorials/datacenter-operations/federation-network-areas) for more details. ## Create Network Area @@ -36,16 +36,16 @@ successfully. | `POST` | `/operator/area` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ---------------- | | `NO` | `none` | `none` | `operator:write` | -The corresponding CLI command is [`consul operator area create`](/commands/operator/area#create). +The corresponding CLI command is [`consul operator area create`](/consul/commands/operator/area#create). ### Query Parameters @@ -105,16 +105,16 @@ This endpoint lists all network areas. | `GET` | `/operator/area` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | --------------- | | `YES` | `all` | `none` | `operator:read` | -The corresponding CLI command is [`consul operator area list`](/commands/operator/area#list). +The corresponding CLI command is [`consul operator area list`](/consul/commands/operator/area#list). ### Query Parameters @@ -149,16 +149,16 @@ This endpoint updates a network area to the given configuration. | `PUT` | `/operator/area/:uuid` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ---------------- | | `NO` | `none` | `none` | `operator:write` | -The corresponding CLI command is [`consul operator area update`](/commands/operator/area#update). +The corresponding CLI command is [`consul operator area update`](/consul/commands/operator/area#update). ### Query Parameters @@ -196,10 +196,10 @@ This endpoint lists a specific network area. | `GET` | `/operator/area/:uuid` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | --------------- | @@ -242,16 +242,16 @@ This endpoint deletes a specific network area. | `DELETE` | `/operator/area/:uuid` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ---------------- | | `NO` | `none` | `none` | `operator:write` | -The corresponding CLI command is [`consul operator area delete`](/commands/operator/area#delete). +The corresponding CLI command is [`consul operator area delete`](/consul/commands/operator/area#delete). ### Path Parameters @@ -280,16 +280,16 @@ area. | `PUT` | `/operator/area/:uuid/join` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ---------------- | | `NO` | `none` | `none` | `operator:write` | -The corresponding CLI command is [`consul operator area join`](/commands/operator/area#join). +The corresponding CLI command is [`consul operator area join`](/consul/commands/operator/area#join). ### Path Parameters @@ -355,16 +355,16 @@ network area. | `GET` | `/operator/area/:uuid/members` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | --------------- | | `NO` | `none` | `none` | `operator:read` | -The corresponding CLI command is [`consul operator area members`](/commands/operator/area#members). +The corresponding CLI command is [`consul operator area members`](/consul/commands/operator/area#members). ### Path Parameters @@ -416,7 +416,7 @@ $ curl \ - `Build` has the Consul version running on the node. -- `Protocol` is the [protocol version](/docs/upgrading#protocol-versions) +- `Protocol` is the [protocol version](/consul/docs/upgrading#protocol-versions) being spoken by the node. - `Status` is the current health status of the node, as determined by the @@ -426,4 +426,4 @@ $ curl \ - `RTT` is an estimated network round trip time from the server answering the query to the given server, in nanoseconds. This is computed using [network - coordinates](/docs/architecture/coordinates). + coordinates](/consul/docs/architecture/coordinates). diff --git a/website/content/api-docs/operator/autopilot.mdx b/website/content/api-docs/operator/autopilot.mdx index 2fba68f58c..c03f688b60 100644 --- a/website/content/api-docs/operator/autopilot.mdx +++ b/website/content/api-docs/operator/autopilot.mdx @@ -13,7 +13,7 @@ The `/operator/autopilot` endpoints allow for automatic operator-friendly management of Consul servers including cleanup of dead servers, monitoring the state of the Raft cluster, and stable server introduction. -Please check the [Autopilot tutorial](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations) for more details. +Please check the [Autopilot tutorial](/consul/tutorials/datacenter-operations/autopilot-datacenter-operations) for more details. ## Read Configuration @@ -24,16 +24,16 @@ This endpoint retrieves its latest Autopilot configuration. | `GET` | `/operator/autopilot/configuration` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | --------------- | | `NO` | `none` | `none` | `operator:read` | -The corresponding CLI command is [`consul operator autopilot get-config`](/commands/operator/autopilot#get-config). +The corresponding CLI command is [`consul operator autopilot get-config`](/consul/commands/operator/autopilot#get-config). ### Query Parameters @@ -68,7 +68,7 @@ $ curl \ ``` For more information about the Autopilot configuration options, see the -[agent configuration section](/docs/agent/config/config-files#autopilot). +[agent configuration section](/consul/docs/agent/config/config-files#autopilot). ## Update Configuration @@ -79,16 +79,16 @@ This endpoint updates the Autopilot configuration of the cluster. | `PUT` | `/operator/autopilot/configuration` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ---------------- | | `NO` | `none` | `none` | `operator:write` | -The corresponding CLI command is [`consul operator autopilot set-config`](/commands/operator/autopilot#set-config). +The corresponding CLI command is [`consul operator autopilot set-config`](/consul/commands/operator/autopilot#set-config). ### Query Parameters @@ -159,10 +159,10 @@ This endpoint queries the health of the autopilot status. | `GET` | `/operator/autopilot/health` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | --------------- | @@ -263,16 +263,16 @@ This endpoint queries the health of the autopilot status. | `GET` | `/operator/autopilot/state` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | --------------- | | `NO` | `none` | `none` | `operator:read` | -The corresponding CLI command is [`consul operator autopilot state`](/commands/operator/autopilot#state). +The corresponding CLI command is [`consul operator autopilot state`](/consul/commands/operator/autopilot#state). ### Query Parameters @@ -327,7 +327,7 @@ $ curl \ - `OptimisticFailuretolerance` is the maximum number of servers that could fail in the right order over the right period of time without causing an outage. This value is only useful when using the [Redundancy - Zones feature](/docs/enterprise/redundancy) with autopilot. + Zones feature](/consul/docs/enterprise/redundancy) with autopilot. - `Servers` is a mapping of server ID to an object holding detailed information about that server. The format of the detailed info is documented in its own section. diff --git a/website/content/api-docs/operator/index.mdx b/website/content/api-docs/operator/index.mdx index 6bfaf034d2..3be515ac9c 100644 --- a/website/content/api-docs/operator/index.mdx +++ b/website/content/api-docs/operator/index.mdx @@ -11,13 +11,13 @@ description: |- The `/operator` endpoints provide cluster-level tools for Consul operators, such as interacting with the Raft subsystem. For a CLI to perform these operations manually, please check the documentation for the -[`consul operator`](/commands/operator) command. +[`consul operator`](/consul/commands/operator) command. If ACLs are enabled then a token with operator privileges may be required in -order to use this interface. Check the [ACL Rules documentation](/docs/security/acl/acl-rules#operator-rules) +order to use this interface. Check the [ACL Rules documentation](/consul/docs/security/acl/acl-rules#operator-rules) for more information. -Check the [Outage Recovery](https://learn.hashicorp.com/tutorials/consul/recovery-outage) tutorial for some examples of +Check the [Outage Recovery](/consul/tutorials/datacenter-operations/recovery-outage) tutorial for some examples of how these capabilities are used. Please choose a sub-section in the navigation for more information. diff --git a/website/content/api-docs/operator/keyring.mdx b/website/content/api-docs/operator/keyring.mdx index 59c6c1b0a1..ec0b14fc8d 100644 --- a/website/content/api-docs/operator/keyring.mdx +++ b/website/content/api-docs/operator/keyring.mdx @@ -9,7 +9,7 @@ description: |- # Keyring Operator HTTP API The `/operator/keyring` endpoints allow for management of the gossip encryption -keyring. Please see the [Gossip Protocol Guide](/docs/architecture/gossip) for +keyring. Please see the [Gossip Protocol Guide](/consul/docs/architecture/gossip) for more details on the gossip protocol and its use. ## List Gossip Encryption Keys @@ -26,16 +26,16 @@ read privileges. | `GET` | `/operator/keyring` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | -------------- | | `NO` | `none` | `none` | `keyring:read` | -The corresponding CLI command is [`consul keyring -list`](/commands/keyring#list). +The corresponding CLI command is [`consul keyring -list`](/consul/commands/keyring#list). ### Query Parameters @@ -113,16 +113,16 @@ This endpoint installs a new gossip encryption key into the cluster. | `POST` | `/operator/keyring` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | --------------- | | `NO` | `none` | `none` | `keyring:write` | -The corresponding CLI command is [`consul keyring -install`](/commands/keyring#install). +The corresponding CLI command is [`consul keyring -install`](/consul/commands/keyring#install). ### Query Parameters @@ -162,16 +162,16 @@ installed before this operation can succeed. | `PUT` | `/operator/keyring` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | --------------- | | `NO` | `none` | `none` | `keyring:write` | -The corresponding CLI command is [`consul keyring -use`](/commands/keyring#use). +The corresponding CLI command is [`consul keyring -use`](/consul/commands/keyring#use). ### Query Parameters @@ -211,16 +211,16 @@ may only be performed on keys which are not currently the primary key. | `DELETE` | `/operator/keyring` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | --------------- | | `NO` | `none` | `none` | `keyring:write` | -The corresponding CLI command is [`consul keyring -remove`](/commands/keyring#remove). +The corresponding CLI command is [`consul keyring -remove`](/consul/commands/keyring#remove). ### Query Parameters diff --git a/website/content/api-docs/operator/license.mdx b/website/content/api-docs/operator/license.mdx index fb60f28964..c04b668904 100644 --- a/website/content/api-docs/operator/license.mdx +++ b/website/content/api-docs/operator/license.mdx @@ -22,16 +22,16 @@ This endpoint gets information about the current license. | `GET` | `/operator/license` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `all` | `none` | `none` | -The corresponding CLI command is [`consul license get`](/commands/license#get). +The corresponding CLI command is [`consul license get`](/consul/commands/license#get). ### Query Parameters @@ -88,16 +88,16 @@ license contents as well as any warning messages regarding its validity. | `PUT` | `/operator/license` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ---------------- | | `NO` | `none` | `none` | `operator:write` | -The corresponding CLI command is [`consul license put`](/commands/license#put). +The corresponding CLI command is [`consul license put`](/consul/commands/license#put). ### Query Parameters @@ -159,16 +159,16 @@ This endpoint resets the Consul license to the license included in the Enterpris | `DELETE` | `/operator/license` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ---------------- | | `NO` | `none` | `none` | `operator:write` | -The corresponding CLI command is [`consul license reset`](/commands/license#reset). +The corresponding CLI command is [`consul license reset`](/consul/commands/license#reset). ### Query Parameters diff --git a/website/content/api-docs/operator/raft.mdx b/website/content/api-docs/operator/raft.mdx index e22321a182..7b55284644 100644 --- a/website/content/api-docs/operator/raft.mdx +++ b/website/content/api-docs/operator/raft.mdx @@ -11,7 +11,7 @@ description: |- The `/operator/raft` endpoints provide tools for management of Raft the consensus subsystem and cluster quorum. -Please see the [Consensus Protocol Guide](/docs/architecture/consensus) for +Please see the [Consensus Protocol Guide](/consul/docs/architecture/consensus) for more information about Raft consensus protocol and its use. ## Read Configuration @@ -23,10 +23,10 @@ This endpoint reads the current raft configuration. | `GET` | `/operator/raft/configuration` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | --------------------- | ------------- | --------------- | @@ -42,7 +42,7 @@ The table below shows this endpoint's support for Raft configuration from any of the Consul servers. Not setting this will choose the default consistency mode which will forward the request to the leader for processing but not re-confirm the server is still the leader before returning - results. See [default consistency](/api-docs/features/consistency#default) for more details. + results. See [default consistency](/consul/api-docs/features/consistency#default) for more details. ### Sample Request @@ -120,16 +120,16 @@ write privileges. | `DELETE` | `/operator/raft/peer` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ---------------- | | `NO` | `none` | `none` | `operator:write` | -The corresponding CLI command is [`consul operator raft remove-peer`](/commands/operator/raft#remove-peer). +The corresponding CLI command is [`consul operator raft remove-peer`](/consul/commands/operator/raft#remove-peer). ### Query Parameters @@ -156,16 +156,16 @@ The new leader is selected at random unless explicitly specified with the `id` p | `POST` | `/operator/raft/transfer-leader` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ---------------- | | `NO` | `none` | `none` | `operator:write` | -The corresponding CLI command is [`consul operator raft transfer-leader`](/commands/operator/raft#transfer-leader). +The corresponding CLI command is [`consul operator raft transfer-leader`](/consul/commands/operator/raft#transfer-leader). ### Query Parameters diff --git a/website/content/api-docs/operator/segment.mdx b/website/content/api-docs/operator/segment.mdx index 1a8b7ce0a2..e65268e2ad 100644 --- a/website/content/api-docs/operator/segment.mdx +++ b/website/content/api-docs/operator/segment.mdx @@ -29,10 +29,10 @@ This endpoint lists all network areas. | `GET` | `/operator/segment` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | --------------- | diff --git a/website/content/api-docs/peering.mdx b/website/content/api-docs/peering.mdx index 04891c9081..a6afb29d89 100644 --- a/website/content/api-docs/peering.mdx +++ b/website/content/api-docs/peering.mdx @@ -18,10 +18,10 @@ This endpoint generates a peering token. | `POST` | `/peering/token` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ---------------- | @@ -84,10 +84,10 @@ This endpoint returns no data. Success or failure is indicated by the status code returned. The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ---------------- | @@ -147,10 +147,10 @@ This endpoint returns information about a peering connection for the specified p | `GET` | `/peering/:name` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | -------------- | @@ -203,10 +203,10 @@ This endpoint returns no data. Success or failure is indicated by the status code returned. The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ---------------- | @@ -258,10 +258,10 @@ This endpoint lists all the peerings. | `GET` | `/peerings` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | -------------- | diff --git a/website/content/api-docs/query.mdx b/website/content/api-docs/query.mdx index 67b278731b..b3e2dcc252 100644 --- a/website/content/api-docs/query.mdx +++ b/website/content/api-docs/query.mdx @@ -11,13 +11,13 @@ The `/query` endpoints create, update, destroy, and execute prepared queries. Prepared queries allow you to register a complex service query and then execute it later via its ID or name to get a set of healthy nodes that provide a given service. This is particularly useful in combination with Consul's -[DNS Interface](/docs/discovery/dns#prepared-query-lookups) as it allows for much richer queries than +[DNS Interface](/consul/docs/discovery/dns#prepared-query-lookups) as it allows for much richer queries than would be possible given the limited entry points exposed by DNS. -Check the [Geo Failover tutorial](https://learn.hashicorp.com/tutorials/consul/automate-geo-failover) for details and +Check the [Geo Failover tutorial](/consul/tutorials/developer-discovery/automate-geo-failover) for details and examples for using prepared queries to implement geo failover for services. -Check the [prepared query rules](/docs/security/acl/acl-rules#prepared-query-rules) +Check the [prepared query rules](/consul/docs/security/acl/acl-rules#prepared-query-rules) section of the agent ACL documentation for more details about how prepared queries work with Consul's ACL system. @@ -141,10 +141,10 @@ successfully. | `POST` | `/query` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------- | @@ -188,7 +188,7 @@ The table below shows this endpoint's support for - `NearestN` `(int: 0)` - Specifies that the query will be forwarded to up to `NearestN` other datacenters based on their estimated network round - trip time using [Network Coordinates](/docs/architecture/coordinates) + trip time using [Network Coordinates](/consul/docs/architecture/coordinates) from the WAN gossip pool. The median round trip time from the server handling the query to the servers in the remote datacenter is used to determine the priority. @@ -207,7 +207,7 @@ The table below shows this endpoint's support for service instances in the local datacenter. This option cannot be used with `NearestN` or `Datacenters`. - - `Peer` `(string: "")` - Specifies a [cluster peer](/docs/connect/cluster-peering) to use for + - `Peer` `(string: "")` - Specifies a [cluster peer](/consul/docs/connect/cluster-peering) to use for failover. - `Datacenter` `(string: "")` - Specifies a WAN federated datacenter to forward the @@ -226,7 +226,7 @@ The table below shows this endpoint's support for true, only nodes with checks in the passing state will be returned. - `Near` `(string: "")` - Specifies a node to sort near based on distance - sorting using [Network Coordinates](/docs/architecture/coordinates). The + sorting using [Network Coordinates](/consul/docs/architecture/coordinates). The nearest instance to the specified node will be returned first, and subsequent nodes in the response will be sorted in ascending order of estimated round-trip times. If the node given does not exist, the nodes in the response @@ -252,7 +252,7 @@ The table below shows this endpoint's support for key/value pairs that will be used for filtering the query results to services with the given metadata values present. -* `Connect` `(bool: false)` - If true, only [Connect-capable](/docs/connect) services +* `Connect` `(bool: false)` - If true, only [Connect-capable](/consul/docs/connect) services for the specified service name will be returned. This includes both natively integrated services and proxies. For proxies, the proxy name may not match `Service`, because the proxy destination will. Any @@ -318,10 +318,10 @@ This endpoint returns a list of all prepared queries. | `GET` | `/query` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | @@ -380,10 +380,10 @@ given ID, an error is returned. | `PUT` | `/query/:uuid` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------- | @@ -420,10 +420,10 @@ given ID, an error is returned. | `GET` | `/query/:uuid` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | @@ -460,10 +460,10 @@ given ID, an error is returned. | `DELETE` | `/query/:uuid` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------- | @@ -493,17 +493,17 @@ given ID, an error is returned. The HTTP response includes the `X-Consul-Results-Filtered-By-ACLs: true` header if the [`Nodes`](#nodes) response array excludes results due to ACL policy configuration. -Refer to the [HTTP API documentation](/api-docs/api-structure#results-filtered-by-acls) for more information. +Refer to the [HTTP API documentation](/consul/api-docs/api-structure#results-filtered-by-acls) for more information. | Method | Path | Produces | | ------ | ---------------------- | ------------------ | | `GET` | `/query/:uuid/execute` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | --------------------- | @@ -629,10 +629,10 @@ interpolation. | `GET` | `/query/:uuid/explain` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | diff --git a/website/content/api-docs/session.mdx b/website/content/api-docs/session.mdx index 3fbb484b84..8b4884483a 100644 --- a/website/content/api-docs/session.mdx +++ b/website/content/api-docs/session.mdx @@ -18,10 +18,10 @@ node and may be associated with any number of checks. | `PUT` | `/session/create` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | --------------- | @@ -77,7 +77,7 @@ The table below shows this endpoint's support for 86400s). If provided, the session is invalidated if it is not renewed before the TTL expires. The lowest practical TTL should be used to keep the number of managed sessions low. When locks are forcibly expired, such as when following - the [leader election pattern](https://learn.hashicorp.com/tutorials/consul/application-leader-elections) in an application, + the [leader election pattern](/consul/tutorials/developer-configuration/application-leader-elections) in an application, sessions may not be reaped for up to double this TTL, so long TTL values (> 1 hour) should be avoided. Valid time units include "s", "m" and "h". @@ -128,10 +128,10 @@ either a literal `true` or `false`, indicating of whether the destroy was successful. The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | --------------- | @@ -174,10 +174,10 @@ This endpoint returns the requested session information. | `GET` | `/session/info/:uuid` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | -------------- | @@ -237,10 +237,10 @@ This endpoint returns the active sessions for a given node. | `GET` | `/session/node/:node` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | -------------- | @@ -300,10 +300,10 @@ This endpoint returns the list of active sessions. | `GET` | `/session/list` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | -------------- | @@ -358,10 +358,10 @@ TTL, and it extends the expiration by the TTL. | `PUT` | `/session/renew/:uuid` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | --------------- | diff --git a/website/content/api-docs/snapshot.mdx b/website/content/api-docs/snapshot.mdx index 5524d68ccd..69460e9e3f 100644 --- a/website/content/api-docs/snapshot.mdx +++ b/website/content/api-docs/snapshot.mdx @@ -10,7 +10,7 @@ description: |- The `/snapshot` endpoints save and restore the state of the Consul servers for disaster recovery. Snapshots include all state managed by Consul's -Raft [consensus protocol](/docs/architecture/consensus). +Raft [consensus protocol](/consul/docs/architecture/consensus). ## Generate Snapshot @@ -30,16 +30,16 @@ restore. | `GET` | `/snapshot` | `200 application/x-gzip` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `default,stale` | `none` | `management` | -The corresponding CLI command is [`consul snapshot save`](/commands/snapshot/save). +The corresponding CLI command is [`consul snapshot save`](/consul/commands/snapshot/save). ### Query Parameters @@ -84,16 +84,16 @@ version as the cluster that originally took the snapshot. | `PUT` | `/snapshot` | `200 text/plain (empty body)` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `management` | -The corresponding CLI command is [`consul snapshot restore`](/commands/snapshot/restore). +The corresponding CLI command is [`consul snapshot restore`](/consul/commands/snapshot/restore). ### Query Parameters diff --git a/website/content/api-docs/status.mdx b/website/content/api-docs/status.mdx index 603eea2186..1a14e5d4fc 100644 --- a/website/content/api-docs/status.mdx +++ b/website/content/api-docs/status.mdx @@ -23,10 +23,10 @@ running. | `GET` | `/status/leader` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | @@ -60,16 +60,16 @@ determining when a given server has successfully joined the cluster. | `GET` | `/status/peers` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ------------ | | `NO` | `none` | `none` | `none` | -The corresponding CLI command is [`consul operator raft list-peers`](/commands/operator/raft#list-peers). +The corresponding CLI command is [`consul operator raft list-peers`](/consul/commands/operator/raft#list-peers). ### Query Parameters diff --git a/website/content/api-docs/txn.mdx b/website/content/api-docs/txn.mdx index 830b838432..fe2d2af999 100644 --- a/website/content/api-docs/txn.mdx +++ b/website/content/api-docs/txn.mdx @@ -36,10 +36,10 @@ the leader via the Raft consensus protocol. | `PUT` | `/txn` | `application/json` | The table below shows this endpoint's support for -[blocking queries](/api-docs/features/blocking), -[consistency modes](/api-docs/features/consistency), -[agent caching](/api-docs/features/caching), and -[required ACLs](/api-docs/api-structure#authentication). +[blocking queries](/consul/api-docs/features/blocking), +[consistency modes](/consul/api-docs/features/consistency), +[agent caching](/consul/api-docs/features/caching), and +[required ACLs](/consul/api-docs/api-structure#authentication). | Blocking Queries | Consistency Modes | Agent Caching | ACL Required | | ---------------- | ----------------- | ------------- | ---------------------------------------------------------------------------------------------- | @@ -92,7 +92,7 @@ a value of an object specific to that operation. - `Verb` `(string: )` - Specifies the type of operation to perform. - `Node` `(Node: )` - Specifies the node information to use - for the operation. See the [catalog endpoint](/api-docs/catalog#parameters) for the fields in this object. Note the only the node can be specified here, not any services or checks - separate service or check operations must be used for those. + for the operation. See the [catalog endpoint](/consul/api-docs/catalog#parameters) for the fields in this object. Note the only the node can be specified here, not any services or checks - separate service or check operations must be used for those. - `Service` operations have the following fields: @@ -102,14 +102,14 @@ a value of an object specific to that operation. this service operation. - `Service` `(Service: )` - Specifies the service instance information to use - for the operation. See the [catalog endpoint](/api-docs/catalog#parameters) for the fields in this object. + for the operation. See the [catalog endpoint](/consul/api-docs/catalog#parameters) for the fields in this object. - `Check` operations have the following fields: - `Verb` `(string: )` - Specifies the type of operation to perform. - `Check` `(Service: )` - Specifies the check to use - for the operation. See the [catalog endpoint](/api-docs/catalog#parameters) for the fields in this object. + for the operation. See the [catalog endpoint](/consul/api-docs/catalog#parameters) for the fields in this object. Please see the table below for available verbs. diff --git a/website/content/commands/acl/auth-method/create.mdx b/website/content/commands/acl/auth-method/create.mdx index 87e47039cb..2f6d853c4e 100644 --- a/website/content/commands/acl/auth-method/create.mdx +++ b/website/content/commands/acl/auth-method/create.mdx @@ -7,12 +7,12 @@ page_title: 'Commands: ACL Auth Method Create' Command: `consul acl auth-method create` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/auth-method](/api-docs/acl/auth-methods#create-an-auth-method) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/auth-method](/consul/api-docs/acl/auth-methods#create-an-auth-method) The `acl auth-method create` command creates new auth methods. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/auth-method/delete.mdx b/website/content/commands/acl/auth-method/delete.mdx index 4948d6a458..6a078853bf 100644 --- a/website/content/commands/acl/auth-method/delete.mdx +++ b/website/content/commands/acl/auth-method/delete.mdx @@ -7,12 +7,12 @@ page_title: 'Commands: ACL Auth Method Delete' Command: `consul acl auth-method delete` -Corresponding HTTP API Endpoint: [\[DELETE\] /v1/acl/auth-method/:name](/api-docs/acl/auth-methods#delete-an-auth-method) +Corresponding HTTP API Endpoint: [\[DELETE\] /v1/acl/auth-method/:name](/consul/api-docs/acl/auth-methods#delete-an-auth-method) The `acl auth-method delete` command deletes an auth method. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/auth-method/index.mdx b/website/content/commands/acl/auth-method/index.mdx index db92f6f359..e75a6cec3a 100644 --- a/website/content/commands/acl/auth-method/index.mdx +++ b/website/content/commands/acl/auth-method/index.mdx @@ -11,7 +11,7 @@ The `acl auth-method` command is used to manage Consul's ACL auth methods. It exposes commands for creating, updating, reading, deleting, and listing auth methods. This command is available in Consul 1.5.0 and newer. -ACL auth methods may also be managed via the [HTTP API](/api-docs/acl/auth-methods). +ACL auth methods may also be managed via the [HTTP API](/consul/api-docs/acl/auth-methods). -> **Note:** All of the example subcommands in this document will require a valid Consul token with the appropriate permissions. Either set the diff --git a/website/content/commands/acl/auth-method/list.mdx b/website/content/commands/acl/auth-method/list.mdx index 00dee96418..348dac523c 100644 --- a/website/content/commands/acl/auth-method/list.mdx +++ b/website/content/commands/acl/auth-method/list.mdx @@ -7,12 +7,12 @@ page_title: 'Commands: ACL Auth Method List' Command: `consul acl auth-method list` -Corresponding HTTP API Endpoint: [\[GET\] /v1/acl/auth-methods](/api-docs/acl/auth-methods#list-auth-methods) +Corresponding HTTP API Endpoint: [\[GET\] /v1/acl/auth-methods](/consul/api-docs/acl/auth-methods#list-auth-methods) The `acl auth-method list` command lists all auth methods. By default it will not show metadata. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/auth-method/read.mdx b/website/content/commands/acl/auth-method/read.mdx index c8b2eaa7b9..c9cc50b80b 100644 --- a/website/content/commands/acl/auth-method/read.mdx +++ b/website/content/commands/acl/auth-method/read.mdx @@ -7,12 +7,12 @@ page_title: 'Commands: ACL Auth Method Read' Command: `consul acl auth-method read` -Corresponding HTTP API Endpoint: [\[GET\] /v1/acl/auth-method/:name](/api-docs/acl/auth-methods#read-an-auth-method) +Corresponding HTTP API Endpoint: [\[GET\] /v1/acl/auth-method/:name](/consul/api-docs/acl/auth-methods#read-an-auth-method) The `acl auth-method read` command reads and displays an auth method's details. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/auth-method/update.mdx b/website/content/commands/acl/auth-method/update.mdx index c41af9aa59..8c9907c16a 100644 --- a/website/content/commands/acl/auth-method/update.mdx +++ b/website/content/commands/acl/auth-method/update.mdx @@ -7,15 +7,15 @@ page_title: 'Commands: ACL Auth Method Update' Command: `consul acl auth-method update` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/auth-method/:name](/api-docs/acl/auth-methods#update-an-auth-method) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/auth-method/:name](/consul/api-docs/acl/auth-methods#update-an-auth-method) The `acl auth-method update` command is used to update an auth method. The default operations is to merge the current auth method with those values provided to the command invocation. Therefore to update just one field, only the `-name` options and the option to modify must be provided. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/binding-rule/create.mdx b/website/content/commands/acl/binding-rule/create.mdx index ecf1d96909..4f3c0ebc7f 100644 --- a/website/content/commands/acl/binding-rule/create.mdx +++ b/website/content/commands/acl/binding-rule/create.mdx @@ -7,12 +7,12 @@ page_title: 'Commands: ACL Binding Rule Create' Command: `consul acl binding-rule create` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/binding-rule](/api-docs/acl/binding-rules#create-a-binding-rule) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/binding-rule](/consul/api-docs/acl/binding-rules#create-a-binding-rule) The `acl binding-rule create` command creates new binding rules. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/binding-rule/delete.mdx b/website/content/commands/acl/binding-rule/delete.mdx index 41cf6d8af0..175241f183 100644 --- a/website/content/commands/acl/binding-rule/delete.mdx +++ b/website/content/commands/acl/binding-rule/delete.mdx @@ -7,12 +7,12 @@ page_title: 'Commands: ACL Binding Rule Delete' Command: `consul acl binding-rule delete` -Corresponding HTTP API Endpoint: [\[DELETE\] /v1/acl/binding-rule/:id](/api-docs/acl/binding-rules#delete-a-binding-rule) +Corresponding HTTP API Endpoint: [\[DELETE\] /v1/acl/binding-rule/:id](/consul/api-docs/acl/binding-rules#delete-a-binding-rule) The `acl binding-rule delete` command deletes a binding rule. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/binding-rule/index.mdx b/website/content/commands/acl/binding-rule/index.mdx index 911ada43d3..01fb442329 100644 --- a/website/content/commands/acl/binding-rule/index.mdx +++ b/website/content/commands/acl/binding-rule/index.mdx @@ -11,7 +11,7 @@ The `acl binding-rule` command is used to manage Consul's ACL binding rules. It exposes commands for creating, updating, reading, deleting, and listing binding rules. This command is available in Consul 1.5.0 and newer. -ACL binding rules may also be managed via the [HTTP API](/api-docs/acl/binding-rules). +ACL binding rules may also be managed via the [HTTP API](/consul/api-docs/acl/binding-rules). -> **Note:** All of the example subcommands in this document will require a valid Consul token with the appropriate permissions. Either set the diff --git a/website/content/commands/acl/binding-rule/list.mdx b/website/content/commands/acl/binding-rule/list.mdx index 2092b2a79d..e642e3f6b7 100644 --- a/website/content/commands/acl/binding-rule/list.mdx +++ b/website/content/commands/acl/binding-rule/list.mdx @@ -7,12 +7,12 @@ page_title: 'Commands: ACL Binding Rule List' Command: `consul acl binding-rule list` -Corresponding HTTP API Endpoint: [\[GET\] /v1/acl/binding-rules](/api-docs/acl/binding-rules#list-binding-rules) +Corresponding HTTP API Endpoint: [\[GET\] /v1/acl/binding-rules](/consul/api-docs/acl/binding-rules#list-binding-rules) The `acl binding-rule list` command lists all binding rules. By default it will not show metadata. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/binding-rule/read.mdx b/website/content/commands/acl/binding-rule/read.mdx index f5f613cdc7..62b2502264 100644 --- a/website/content/commands/acl/binding-rule/read.mdx +++ b/website/content/commands/acl/binding-rule/read.mdx @@ -7,12 +7,12 @@ page_title: 'Commands: ACL Binding Rule Read' Command: `consul acl binding-rule read` -Corresponding HTTP API Endpoint: [\[GET\] /v1/acl/binding-rule/:id](/api-docs/acl/binding-rules#read-a-binding-rule) +Corresponding HTTP API Endpoint: [\[GET\] /v1/acl/binding-rule/:id](/consul/api-docs/acl/binding-rules#read-a-binding-rule) The `acl binding-rule read` command reads and displays a binding rules details. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/binding-rule/update.mdx b/website/content/commands/acl/binding-rule/update.mdx index f19a69dba4..d6d1870e78 100644 --- a/website/content/commands/acl/binding-rule/update.mdx +++ b/website/content/commands/acl/binding-rule/update.mdx @@ -7,15 +7,15 @@ page_title: 'Commands: ACL Binding Rule Update' Command: `consul acl binding-rule update` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/binding-rule/:id](/api-docs/acl/binding-rules#update-a-binding-rule) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/binding-rule/:id](/consul/api-docs/acl/binding-rules#update-a-binding-rule) The `acl binding-rule update` command is used to update a binding rule. The default operations is to merge the current binding rule with those values provided to the command invocation. Therefore to update just one field, only the `-id` option and the option to modify must be provided. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/bootstrap.mdx b/website/content/commands/acl/bootstrap.mdx index e9c029925c..3b14fdb0b9 100644 --- a/website/content/commands/acl/bootstrap.mdx +++ b/website/content/commands/acl/bootstrap.mdx @@ -7,15 +7,15 @@ page_title: 'Commands: ACL Bootstrap' Command: `consul acl bootstrap` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/bootstrap](/api-docs/acl#bootstrap-acls) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/bootstrap](/consul/api-docs/acl#bootstrap-acls) The `acl bootstrap` command generates a new token with unlimited privileges to use for management purposes and outputs the token's details. Optionally, you can provide a Secret ID to use instead of generating a completely new token. You can create this bootstrapping token only once and afterwards bootstrapping will be disabled. If all tokens are lost and you need to bootstrap again you can follow the bootstrap [reset procedure](https://learn.hashicorp.com/consul/security-networking/acl-troubleshooting?utm_source=docs). -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/index.mdx b/website/content/commands/acl/index.mdx index 93547bc341..306f5d53f5 100644 --- a/website/content/commands/acl/index.mdx +++ b/website/content/commands/acl/index.mdx @@ -12,7 +12,7 @@ line. It exposes top-level commands for bootstrapping the ACL system, managing tokens and policies, translating legacy rules, and setting the tokens for use by an agent. -ACLs are also accessible via the [HTTP API](/api-docs/acl). +ACLs are also accessible via the [HTTP API](/consul/api-docs/acl). Bootstrap Consul's ACLs: diff --git a/website/content/commands/acl/policy/create.mdx b/website/content/commands/acl/policy/create.mdx index 62779edb54..e31c2a037b 100644 --- a/website/content/commands/acl/policy/create.mdx +++ b/website/content/commands/acl/policy/create.mdx @@ -7,7 +7,7 @@ page_title: 'Commands: ACL Policy Create' Command: `consul acl policy create` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/policy](/api-docs/acl/policies#create-a-policy) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/policy](/consul/api-docs/acl/policies#create-a-policy) The `acl policy create` command creates new policies. The policies rules can either be set explicitly or the `-from-token` parameter may be used to load the rules from a legacy ACL token. When loading @@ -19,8 +19,8 @@ from stdin, a file or the raw value. To use stdin pass `-` as the value. To load the value from a file prefix the value with an `@`. Any other values will be used directly. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/policy/delete.mdx b/website/content/commands/acl/policy/delete.mdx index 8c8d220cee..f41036c916 100644 --- a/website/content/commands/acl/policy/delete.mdx +++ b/website/content/commands/acl/policy/delete.mdx @@ -7,12 +7,12 @@ page_title: 'Commands: ACL Policy Delete' Command: `consul acl policy delete` -Corresponding HTTP API Endpoint: [\[DELETE\] /v1/acl/policy/:id](/api-docs/acl/policies#delete-a-policy) +Corresponding HTTP API Endpoint: [\[DELETE\] /v1/acl/policy/:id](/consul/api-docs/acl/policies#delete-a-policy) The `acl policy delete` command deletes a policy. Policies may be deleted by their ID or by name. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/policy/index.mdx b/website/content/commands/acl/policy/index.mdx index dcfdbdf311..f3d94f51fb 100644 --- a/website/content/commands/acl/policy/index.mdx +++ b/website/content/commands/acl/policy/index.mdx @@ -11,7 +11,7 @@ The `acl policy` command is used to manage Consul's ACL policies. It exposes commands for creating, updating, reading, deleting, and listing policies. This command is available in Consul 1.4.0 and newer. -ACL policies may also be managed via the [HTTP API](/api-docs/acl/policies). +ACL policies may also be managed via the [HTTP API](/consul/api-docs/acl/policies). -> **Note:** All of the example subcommands in this document will require a valid Consul token with the appropriate permissions. Either set the diff --git a/website/content/commands/acl/policy/list.mdx b/website/content/commands/acl/policy/list.mdx index 32b8d5a9e7..fe78f4167b 100644 --- a/website/content/commands/acl/policy/list.mdx +++ b/website/content/commands/acl/policy/list.mdx @@ -7,12 +7,12 @@ page_title: 'Commands: ACL Policy List' Command: `consul acl policy list` -Corresponding HTTP API Endpoint: [\[GET\] /v1/acl/policies](/api-docs/acl/policies#list-policies) +Corresponding HTTP API Endpoint: [\[GET\] /v1/acl/policies](/consul/api-docs/acl/policies#list-policies) The `acl policy list` command lists all policies. By default it will not show metadata. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/policy/read.mdx b/website/content/commands/acl/policy/read.mdx index df74a82e53..e4fbe51e2c 100644 --- a/website/content/commands/acl/policy/read.mdx +++ b/website/content/commands/acl/policy/read.mdx @@ -7,12 +7,12 @@ page_title: 'Commands: ACL Policy Read' Command: `consul acl policy read` -Corresponding HTTP API Endpoints: [\[GET\] /v1/acl/policy/:id](/api-docs/acl/policies#read-a-policy), [\[GET\] /v1/acl/policy/name/:name](/api-docs/acl/policies#read-a-policy-by-name) +Corresponding HTTP API Endpoints: [\[GET\] /v1/acl/policy/:id](/consul/api-docs/acl/policies#read-a-policy), [\[GET\] /v1/acl/policy/name/:name](/consul/api-docs/acl/policies#read-a-policy-by-name) The `acl policy read` command reads and displays a policies details. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/policy/update.mdx b/website/content/commands/acl/policy/update.mdx index b417ddd55c..a4229b61a5 100644 --- a/website/content/commands/acl/policy/update.mdx +++ b/website/content/commands/acl/policy/update.mdx @@ -7,7 +7,7 @@ page_title: 'Commands: ACL Policy Update' Command: `consul acl policy update` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/policy/:id](/api-docs/acl/policies#update-a-policy) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/policy/:id](/consul/api-docs/acl/policies#update-a-policy) The `acl policy update` command is used to update a policy. The default operations is to merge the current policy with those values provided to the command invocation. Therefore to update just one field, only @@ -15,8 +15,8 @@ the `-id` or `-name` options and the option to modify must be provided. Note tha policies requires both the `-id` and `-name` as the new name cannot yet be used to lookup the policy. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/role/create.mdx b/website/content/commands/acl/role/create.mdx index f84c145e21..3e4edec5dd 100644 --- a/website/content/commands/acl/role/create.mdx +++ b/website/content/commands/acl/role/create.mdx @@ -7,12 +7,12 @@ page_title: 'Commands: ACL Role Create' Command: `consul acl role create` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/role](/api-docs/acl/roles#create-a-role) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/role](/consul/api-docs/acl/roles#create-a-role) The `acl role create` command creates new roles. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/role/delete.mdx b/website/content/commands/acl/role/delete.mdx index b362b5c031..592914daac 100644 --- a/website/content/commands/acl/role/delete.mdx +++ b/website/content/commands/acl/role/delete.mdx @@ -7,12 +7,12 @@ page_title: 'Commands: ACL Role Delete' Command: `consul acl role delete` -Corresponding HTTP API Endpoint: [\[DELETE\] /v1/acl/role/:id](/api-docs/acl/roles#delete-a-role) +Corresponding HTTP API Endpoint: [\[DELETE\] /v1/acl/role/:id](/consul/api-docs/acl/roles#delete-a-role) The `acl role delete` command deletes a role. Roles may be deleted by their ID or by name. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/role/index.mdx b/website/content/commands/acl/role/index.mdx index b14cd6f63c..90a736d40d 100644 --- a/website/content/commands/acl/role/index.mdx +++ b/website/content/commands/acl/role/index.mdx @@ -11,7 +11,7 @@ The `acl role` command is used to manage Consul's ACL roles. It exposes commands for creating, updating, reading, deleting, and listing roles. This command is available in Consul 1.5.0 and newer. -ACL roles may also be managed via the [HTTP API](/api-docs/acl/roles). +ACL roles may also be managed via the [HTTP API](/consul/api-docs/acl/roles). -> **Note:** All of the example subcommands in this document will require a valid Consul token with the appropriate permissions. Either set the diff --git a/website/content/commands/acl/role/list.mdx b/website/content/commands/acl/role/list.mdx index 960af79299..06220e266f 100644 --- a/website/content/commands/acl/role/list.mdx +++ b/website/content/commands/acl/role/list.mdx @@ -7,12 +7,12 @@ page_title: 'Commands: ACL Role List' Command: `consul acl role list` -Corresponding HTTP API Endpoint: [\[GET\] /v1/acl/roles](/api-docs/acl/roles#list-roles) +Corresponding HTTP API Endpoint: [\[GET\] /v1/acl/roles](/consul/api-docs/acl/roles#list-roles) The `acl role list` command lists all roles. By default it will not show metadata. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/role/read.mdx b/website/content/commands/acl/role/read.mdx index b9c9fcddff..38342490b5 100644 --- a/website/content/commands/acl/role/read.mdx +++ b/website/content/commands/acl/role/read.mdx @@ -7,12 +7,12 @@ page_title: 'Commands: ACL Role Read' Command: `consul acl role read` -Corresponding HTTP API Endpoints: [\[GET\] /v1/acl/role/:id](/api-docs/acl/roles#read-a-role), [\[GET\] /v1/acl/role/name/:name](/api-docs/acl/roles#read-a-role-by-name) +Corresponding HTTP API Endpoints: [\[GET\] /v1/acl/role/:id](/consul/api-docs/acl/roles#read-a-role), [\[GET\] /v1/acl/role/name/:name](/consul/api-docs/acl/roles#read-a-role-by-name) The `acl role read` command reads and displays a roles details. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/role/update.mdx b/website/content/commands/acl/role/update.mdx index fb3df976f1..fc1f56c9cb 100644 --- a/website/content/commands/acl/role/update.mdx +++ b/website/content/commands/acl/role/update.mdx @@ -7,7 +7,7 @@ page_title: 'Commands: ACL Role Update' Command: `consul acl role update` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/role/:id](/api-docs/acl/roles#update-a-role) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/role/:id](/consul/api-docs/acl/roles#update-a-role) The `acl role update` command is used to update a role. The default operations is to merge the current role with those values provided to the command invocation. Therefore to @@ -15,8 +15,8 @@ update just one field, only the `-id` or `-name` options and the option to modify must be provided. Note that renaming roles requires both the `-id` and `-name` as the new name cannot yet be used to lookup the role. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/set-agent-token.mdx b/website/content/commands/acl/set-agent-token.mdx index fd8cb403e3..a57eedb280 100644 --- a/website/content/commands/acl/set-agent-token.mdx +++ b/website/content/commands/acl/set-agent-token.mdx @@ -7,17 +7,17 @@ page_title: 'Commands: ACL Set Agent Token' Command: `consul acl set-agent-token` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/token/:type](/api-docs/agent#update-acl-tokens) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/token/:type](/consul/api-docs/agent#update-acl-tokens) This command updates the ACL tokens currently in use by the agent. It can be used to introduce ACL tokens to the agent for the first time, or to update tokens that were initially loaded from the agent's configuration. Tokens are not persisted unless -[`acl.enable_token_persistence`](/docs/agent/config/config-files#acl_enable_token_persistence) +[`acl.enable_token_persistence`](/consul/docs/agent/config/config-files#acl_enable_token_persistence) is `true`, so tokens will need to be updated again if that option is `false` and the agent is restarted. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/token/clone.mdx b/website/content/commands/acl/token/clone.mdx index 9e8d9df0e1..a043730b01 100644 --- a/website/content/commands/acl/token/clone.mdx +++ b/website/content/commands/acl/token/clone.mdx @@ -7,12 +7,12 @@ page_title: 'Commands: ACL Token Clone' Command: `consul acl token clone` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/token/:AccessorID/clone](/api-docs/acl/tokens#clone-a-token) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/token/:AccessorID/clone](/consul/api-docs/acl/tokens#clone-a-token) The `acl token clone` command clones an existing token. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/token/create.mdx b/website/content/commands/acl/token/create.mdx index 77128d700e..bcb9f9cba2 100644 --- a/website/content/commands/acl/token/create.mdx +++ b/website/content/commands/acl/token/create.mdx @@ -7,14 +7,14 @@ page_title: 'Commands: ACL Token Create' Command: `consul acl token create` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/token](/api-docs/acl/tokens#create-a-token) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/token](/consul/api-docs/acl/tokens#create-a-token) This command creates new tokens. When creating a new token, policies may be linked using either the `-policy-id` or the `-policy-name` options. When specifying policies by IDs you may use a unique prefix of the UUID as a shortcut for specifying the entire UUID. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/token/delete.mdx b/website/content/commands/acl/token/delete.mdx index 267201c762..27c5057abc 100644 --- a/website/content/commands/acl/token/delete.mdx +++ b/website/content/commands/acl/token/delete.mdx @@ -7,12 +7,12 @@ page_title: 'Commands: ACL Token Delete' Command: `consul acl token delete` -Corresponding HTTP API Endpoint: [\[DELETE\] /v1/acl/token/:AccessorID](/api-docs/acl/tokens#delete-a-token) +Corresponding HTTP API Endpoint: [\[DELETE\] /v1/acl/token/:AccessorID](/consul/api-docs/acl/tokens#delete-a-token) The `acl token delete` command deletes a token. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/token/index.mdx b/website/content/commands/acl/token/index.mdx index 9c3e497d73..37b69475fd 100644 --- a/website/content/commands/acl/token/index.mdx +++ b/website/content/commands/acl/token/index.mdx @@ -11,7 +11,7 @@ The `acl token` command is used to manage Consul's ACL tokens. It exposes commands for creating, updating, reading, deleting, and listing tokens. This command is available in Consul 1.4.0 and newer. -ACL tokens may also be managed via the [HTTP API](/api-docs/acl/tokens). +ACL tokens may also be managed via the [HTTP API](/consul/api-docs/acl/tokens). -> **Note:** All of the example subcommands in this document will require a valid Consul token with the appropriate permissions. Either set the diff --git a/website/content/commands/acl/token/list.mdx b/website/content/commands/acl/token/list.mdx index c77d53ac30..6226c902c5 100644 --- a/website/content/commands/acl/token/list.mdx +++ b/website/content/commands/acl/token/list.mdx @@ -7,12 +7,12 @@ page_title: 'Commands: ACL Token List' Command: `consul acl token list` -Corresponding HTTP API Endpoint: [\[GET\] /v1/acl/tokens](/api-docs/acl/tokens#list-tokens) +Corresponding HTTP API Endpoint: [\[GET\] /v1/acl/tokens](/consul/api-docs/acl/tokens#list-tokens) The `acl token list` command lists all tokens. By default it will not show metadata. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/token/read.mdx b/website/content/commands/acl/token/read.mdx index 8e99297460..4d061e3cc9 100644 --- a/website/content/commands/acl/token/read.mdx +++ b/website/content/commands/acl/token/read.mdx @@ -7,12 +7,12 @@ page_title: 'Commands: ACL Token Read' Command: `consul acl token read` -Corresponding HTTP API Endpoint: [\[GET\] /v1/acl/token/:AccessorID](/api-docs/acl/tokens#read-a-token) +Corresponding HTTP API Endpoint: [\[GET\] /v1/acl/token/:AccessorID](/consul/api-docs/acl/tokens#read-a-token) The `acl token read` command reads and displays a token details. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/token/update.mdx b/website/content/commands/acl/token/update.mdx index 9d1c68e2d8..957c36e26d 100644 --- a/website/content/commands/acl/token/update.mdx +++ b/website/content/commands/acl/token/update.mdx @@ -7,13 +7,13 @@ page_title: 'Commands: ACL Token Update' Command: `consul acl token update` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/token/:AccessorID](/api-docs/acl/tokens#update-a-token) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/acl/token/:AccessorID](/consul/api-docs/acl/tokens#update-a-token) The `acl token update` command will update a token. Some parts of the token like whether the token is local to the datacenter cannot be changed. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/acl/translate-rules.mdx b/website/content/commands/acl/translate-rules.mdx index e0f7fc57c0..e75d519b2c 100644 --- a/website/content/commands/acl/translate-rules.mdx +++ b/website/content/commands/acl/translate-rules.mdx @@ -10,12 +10,12 @@ It will be removed in a future major release when support for the legacy ACL sys Command: `consul acl translate-rules` -Corresponding HTTP API Endpoint: [\[GET\] /v1/acl/rules/translate/:accessor_id](/api-docs/acl#translate-a-legacy-token-s-rules) +Corresponding HTTP API Endpoint: [\[GET\] /v1/acl/rules/translate/:accessor_id](/consul/api-docs/acl#translate-a-legacy-token-s-rules) This command translates the legacy ACL rule syntax into the new syntax. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/agent.mdx b/website/content/commands/agent.mdx index cfdbdc47b7..6e2a752411 100644 --- a/website/content/commands/agent.mdx +++ b/website/content/commands/agent.mdx @@ -14,6 +14,6 @@ performs the important task of maintaining membership information, running checks, announcing services, handling queries, etc. Due to the power and flexibility of this command, the Consul agent -is documented in its own section. See the [Consul Agent](/docs/agent) +is documented in its own section. See the [Consul Agent](/consul/docs/agent) section for more information on how to use this command and the options it has. diff --git a/website/content/commands/catalog/datacenters.mdx b/website/content/commands/catalog/datacenters.mdx index 2287d40b70..daefae6bdf 100644 --- a/website/content/commands/catalog/datacenters.mdx +++ b/website/content/commands/catalog/datacenters.mdx @@ -7,12 +7,12 @@ page_title: 'Commands: Catalog List Datacenters' Command: `consul catalog datacenters` -Corresponding HTTP API Endpoint: [\[GET\] /v1/catalog/datacenters](/api-docs/catalog#list-datacenters) +Corresponding HTTP API Endpoint: [\[GET\] /v1/catalog/datacenters](/consul/api-docs/catalog#list-datacenters) The `catalog datacenters` command prints all known datacenters. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/catalog/index.mdx b/website/content/commands/catalog/index.mdx index 63b213a6c4..c95c1343d9 100644 --- a/website/content/commands/catalog/index.mdx +++ b/website/content/commands/catalog/index.mdx @@ -11,7 +11,7 @@ The `catalog` command is used to interact with Consul's catalog via the command line. It exposes top-level commands for reading and filtering data from the registry. -The catalog is also accessible via the [HTTP API](/api-docs/catalog). +The catalog is also accessible via the [HTTP API](/consul/api-docs/catalog). ## Basic Examples diff --git a/website/content/commands/catalog/nodes.mdx b/website/content/commands/catalog/nodes.mdx index ec0494aceb..37a9b59b08 100644 --- a/website/content/commands/catalog/nodes.mdx +++ b/website/content/commands/catalog/nodes.mdx @@ -7,14 +7,14 @@ page_title: 'Commands: Catalog List Nodes' Command: `consul catalog nodes` -Corresponding HTTP API Endpoint: [\[GET\] /v1/catalog/nodes](/api-docs/catalog#list-nodes) +Corresponding HTTP API Endpoint: [\[GET\] /v1/catalog/nodes](/consul/api-docs/catalog#list-nodes) The `catalog nodes` command prints all known nodes and metadata about them. It can also query for nodes that match a particular metadata or provide a particular service. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -78,7 +78,7 @@ Usage: `consul catalog nodes [options]` - `-filter=` - Expression to use for filtering the results. Can be passed via stdin by using `-` for the value or from a file by passing `@`. - See the [`/catalog/nodes` API documentation](/api-docs/catalog#filtering) for a + See the [`/catalog/nodes` API documentation](/consul/api-docs/catalog#filtering) for a description of what is filterable. #### Enterprise Options diff --git a/website/content/commands/catalog/services.mdx b/website/content/commands/catalog/services.mdx index 54630aadb0..4082d444eb 100644 --- a/website/content/commands/catalog/services.mdx +++ b/website/content/commands/catalog/services.mdx @@ -7,14 +7,14 @@ page_title: 'Commands: Catalog List Services' Command: `consul catalog services` -Corresponding HTTP API Endpoint: [\[GET\] /v1/catalog/services](/api-docs/catalog#list-services) +Corresponding HTTP API Endpoint: [\[GET\] /v1/catalog/services](/consul/api-docs/catalog#list-services) The `catalog services` command prints all known services. It can also query for services that match particular metadata or list the services that a particular node provides. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/config/delete.mdx b/website/content/commands/config/delete.mdx index f24c048548..f1dc92e5bc 100644 --- a/website/content/commands/config/delete.mdx +++ b/website/content/commands/config/delete.mdx @@ -7,14 +7,14 @@ page_title: 'Commands: Config Delete' Command: `consul config delete` -Corresponding HTTP API Endpoint: [\[DELETE\] /v1/config/:kind/:name](/api-docs/config#delete-configuration) +Corresponding HTTP API Endpoint: [\[DELETE\] /v1/config/:kind/:name](/consul/api-docs/config#delete-configuration) The `config delete` command deletes the configuration entry specified by the -kind and name. See the [configuration entries docs](/docs/agent/config-entries) +kind and name. See the [configuration entries docs](/consul/docs/agent/config-entries) for more details about configuration entries. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required1 | diff --git a/website/content/commands/config/index.mdx b/website/content/commands/config/index.mdx index 891e1ffcec..0ebb0b4e73 100644 --- a/website/content/commands/config/index.mdx +++ b/website/content/commands/config/index.mdx @@ -10,9 +10,9 @@ Command: `consul config` The `config` command is used to interact with Consul's central configuration system. It exposes commands for creating, updating, reading, and deleting different kinds of config entries. See the -[agent configuration](/docs/agent/config/config-files#enable_central_service_config) +[agent configuration](/consul/docs/agent/config/config-files#enable_central_service_config) for more information on how to enable this functionality for centrally -configuring services and [configuration entries docs](/docs/agent/config-entries) for a description +configuring services and [configuration entries docs](/consul/docs/agent/config-entries) for a description of the configuration entries content. ## Usage diff --git a/website/content/commands/config/list.mdx b/website/content/commands/config/list.mdx index 72d4fb0c3e..b87c008f01 100644 --- a/website/content/commands/config/list.mdx +++ b/website/content/commands/config/list.mdx @@ -7,14 +7,14 @@ page_title: 'Commands: Config List' Command: `consul config list` -Corresponding HTTP API Endpoint: [\[GET\] /v1/config/:kind](/api-docs/config#list-configurations) +Corresponding HTTP API Endpoint: [\[GET\] /v1/config/:kind](/consul/api-docs/config#list-configurations) The `config list` command lists all given config entries of the given kind. -See the [configuration entries docs](/docs/agent/config-entries) for more +See the [configuration entries docs](/consul/docs/agent/config-entries) for more details about configuration entries. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required1 | diff --git a/website/content/commands/config/read.mdx b/website/content/commands/config/read.mdx index a978892c07..af983f8245 100644 --- a/website/content/commands/config/read.mdx +++ b/website/content/commands/config/read.mdx @@ -7,15 +7,15 @@ page_title: 'Commands: Config Read' Command: `consul config read` -Corresponding HTTP API Endpoint: [\[GET\] /v1/config/:kind/:name](/api-docs/config#get-configuration) +Corresponding HTTP API Endpoint: [\[GET\] /v1/config/:kind/:name](/consul/api-docs/config#get-configuration) The `config read` command reads the config entry specified by the given kind and name and outputs its JSON representation. See the -[configuration entries docs](/docs/agent/config-entries) for more +[configuration entries docs](/consul/docs/agent/config-entries) for more details about configuration entries. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required1 | diff --git a/website/content/commands/config/write.mdx b/website/content/commands/config/write.mdx index a412f842d1..9ea2a7ad62 100644 --- a/website/content/commands/config/write.mdx +++ b/website/content/commands/config/write.mdx @@ -7,14 +7,14 @@ page_title: 'Commands: Config Write' Command: `consul config write` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/config](/api-docs/config#apply-configuration) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/config](/consul/api-docs/config#apply-configuration) The `config write` command creates or updates a centralized config entry. -See the [configuration entries docs](/docs/agent/config-entries) for more +See the [configuration entries docs](/consul/docs/agent/config-entries) for more details about configuration entries. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required1 | @@ -71,7 +71,7 @@ From stdin: ### Config Entry examples All config entries must have a `Kind` when registered. See -[Service Mesh - Config Entries](/docs/connect/config-entries) for the list of +[Service Mesh - Config Entries](/consul/docs/connect/config-entries) for the list of supported config entries. #### Service defaults diff --git a/website/content/commands/connect/ca.mdx b/website/content/commands/connect/ca.mdx index 587d4379c5..17a76a6222 100644 --- a/website/content/commands/connect/ca.mdx +++ b/website/content/commands/connect/ca.mdx @@ -12,7 +12,7 @@ Command: `consul connect ca` The CA connect command is used to interact with Consul Connect's Certificate Authority subsystem. The command can be used to view or modify the current CA configuration. See the -[Connect CA documentation](/docs/connect/ca) for more information. +[Connect CA documentation](/consul/docs/connect/ca) for more information. ```text Usage: consul connect ca [options] [args] @@ -42,8 +42,8 @@ Subcommands: This command displays the current CA configuration. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -52,7 +52,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint Usage: `consul connect ca get-config [options]` -Corresponding HTTP API Endpoint: [\[GET\] /v1/connect/ca/configuration](/api-docs/connect/ca#get-ca-configuration) +Corresponding HTTP API Endpoint: [\[GET\] /v1/connect/ca/configuration](/consul/api-docs/connect/ca#get-ca-configuration) #### API Options @@ -74,11 +74,11 @@ The output looks like this: ## set-config Modifies the current CA configuration. If this results in a new root certificate -being used, the [Root Rotation](/docs/connect/ca#root-certificate-rotation) process +being used, the [Root Rotation](/consul/docs/connect/ca#root-certificate-rotation) process will be triggered. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -87,7 +87,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint Usage: `consul connect ca set-config [options]` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/connect/ca/configuration](/api-docs/connect/ca#update-ca-configuration) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/connect/ca/configuration](/consul/api-docs/connect/ca#update-ca-configuration) The output looks like this: @@ -99,16 +99,16 @@ The return code will indicate success or failure. ~> **If currently using Vault CA provider:** If you intend to change the CA provider from Vault to another, - or to change the Vault provider's [`RootPKIPath`](/docs/connect/ca/vault#rootpkipath), + or to change the Vault provider's [`RootPKIPath`](/consul/docs/connect/ca/vault#rootpkipath), you must temporarily elevate the privileges of the Vault token or auth method in use as described in the - [Vault CA provider documentation](/docs/connect/ca/vault#additional-vault-acl-policies-for-sensitive-operations). + [Vault CA provider documentation](/consul/docs/connect/ca/vault#additional-vault-acl-policies-for-sensitive-operations). #### Command Options - `-config-file` - (required) Specifies a JSON-formatted file to use for the new configuration. The format of this config file matches the request payload documented in the - [Update CA Configuration API](/api-docs/connect/ca#update-ca-configuration). + [Update CA Configuration API](/consul/api-docs/connect/ca#update-ca-configuration). - `-force-without-cross-signing` `(bool: )` - Indicates that the CA change should be forced to complete even if the current CA doesn't support root cross-signing. @@ -117,7 +117,7 @@ The return code will indicate success or failure. until service mesh proxies and/or Consul client agents receive a new certificate that establishes trust with the new root. Do not use this flag unless you are sure you need it. - Refer to [Forced Rotation Without Cross-Signing](/docs/connect/ca#forced-rotation-without-cross-signing) + Refer to [Forced Rotation Without Cross-Signing](/consul/docs/connect/ca#forced-rotation-without-cross-signing) for more detail. #### API Options diff --git a/website/content/commands/connect/envoy.mdx b/website/content/commands/connect/envoy.mdx index 66fcd89908..4648313335 100644 --- a/website/content/commands/connect/envoy.mdx +++ b/website/content/commands/connect/envoy.mdx @@ -11,7 +11,7 @@ Command: `consul connect envoy` The connect Envoy command is used to generate a bootstrap configuration for [Envoy proxy](https://envoyproxy.io) for use with [Consul -Connect](/docs/connect/). +Connect](/consul/docs/connect/). Refer to the [examples](#examples) for guidance on common use cases, such as [launching a service instance's sidecar proxy @@ -36,7 +36,7 @@ Usage: `consul connect envoy [options] [-- pass-through options]` #### Envoy Options for both Sidecars and Gateways -- `-proxy-id` - The [proxy service](/docs/connect/registration/service-registration) ID. +- `-proxy-id` - The [proxy service](/consul/docs/connect/registration/service-registration) ID. This service ID must already be registered with the local agent unless a gateway is being registered with the `-register` flag. As of Consul 1.8.0, this can also be specified via the `CONNECT_PROXY_ID` environment variable. @@ -56,7 +56,7 @@ Usage: `consul connect envoy [options] [-- pass-through options]` ACL token from `-token` or the environment and so should be handled as a secret. This token grants the identity of any service it has `service:write` permission for and so can be used to access any upstream service that that service is - allowed to access by [Connect intentions](/docs/connect/intentions). + allowed to access by [Connect intentions](/consul/docs/connect/intentions). - `-envoy-version` - The version of envoy that is being started. Default is `1.23.1`. This is required so that the correct configuration can be generated. @@ -131,7 +131,7 @@ compatibility with Envoy and prevent potential issues. Default is `false`. - `-sidecar-for` - The _ID_ (not name if they differ) of the service instance this proxy will represent. The target service doesn't need to exist on the local agent yet but a [sidecar proxy - registration](/docs/connect/registration/service-registration) with + registration](/consul/docs/connect/registration/service-registration) with `proxy.destination_service_id` equal to the passed value must be present. If multiple proxy registrations targeting the same local service instance are present the command will error and `-proxy-id` should be used instead. @@ -167,14 +167,14 @@ compatibility with Envoy and prevent potential issues. Default is `false`. instantiated at the specified IP and port. Consul uses `/ready` HTTP endpoints to check gateway health. The specified IP will also be used by the ingress gateway when instantiating user-defined listeners configured in the - [ingress gateway](/docs/connect/gateways/ingress-gateway) configuration entry. + [ingress gateway](/consul/docs/connect/gateways/ingress-gateway) configuration entry. ~> **Note**: Ensure that user-defined ingress gateway listeners use a different port than the port specified in `-address` so that they do not conflict with the health check endpoint. - `-admin-access-log-path` - - **Deprecated in Consul 1.15.0 in favor of [`proxy-defaults` access logs](/docs/connect/config-entries/proxy-defaults#accesslogs).** + **Deprecated in Consul 1.15.0 in favor of [`proxy-defaults` access logs](/consul/docs/connect/config-entries/proxy-defaults#accesslogs).** The path to write the access log for the administration server. If no access log is desired specify `/dev/null`. By default it will use `/dev/null`. @@ -215,7 +215,7 @@ proxy configuration needed. be used instead. The scheme can also be set to HTTPS by setting the environment variable CONSUL_HTTP_SSL=true. This may be a unix domain socket using `unix:///path/to/socket` if the [agent is configured to - listen](/docs/agent/config/config-files#addresses) that way. + listen](/consul/docs/agent/config/config-files#addresses) that way. -> **Note:** gRPC uses the same TLS settings as the HTTPS API. If HTTPS is enabled then gRPC will require HTTPS @@ -227,7 +227,7 @@ proxy configuration needed. Assume a local service instance is registered on the local agent with a sidecar proxy (using the [sidecar service -registration](/docs/connect/registration/service-registration) helper) as below. +registration](/consul/docs/connect/registration/service-registration) helper) as below. ```hcl service { diff --git a/website/content/commands/connect/expose.mdx b/website/content/commands/connect/expose.mdx index 4b752438c4..97ca3910fc 100644 --- a/website/content/commands/connect/expose.mdx +++ b/website/content/commands/connect/expose.mdx @@ -14,7 +14,7 @@ Command: `consul connect expose` The connect expose subcommand is used to expose a Connect-enabled service through an Ingress gateway by modifying the gateway's configuration and adding an intention to allow traffic from the gateway to the service. See the -[Ingress gateway documentation](/docs/connect/gateways/ingress-gateway) for more information +[Ingress gateway documentation](/consul/docs/connect/gateways/ingress-gateway) for more information about Ingress gateways. ```text diff --git a/website/content/commands/connect/index.mdx b/website/content/commands/connect/index.mdx index 380cbb14e1..da717a8aa8 100644 --- a/website/content/commands/connect/index.mdx +++ b/website/content/commands/connect/index.mdx @@ -8,7 +8,7 @@ page_title: 'Commands: Connect' Command: `consul connect` The `connect` command is used to interact with Consul -[Connect](/docs/connect/intentions) subsystems. It exposes commands for +[Connect](/consul/docs/connect/intentions) subsystems. It exposes commands for running the built-in mTLS proxy and viewing/updating the Certificate Authority (CA) configuration. This command is available in Consul 1.2 and later. diff --git a/website/content/commands/connect/proxy.mdx b/website/content/commands/connect/proxy.mdx index db9d0d3089..2bdfb2a9a2 100644 --- a/website/content/commands/connect/proxy.mdx +++ b/website/content/commands/connect/proxy.mdx @@ -24,14 +24,14 @@ Usage: `consul connect proxy [options]` - `-sidecar-for` - The _ID_ (not name if they differ) of the service instance this proxy will represent. The target service doesn't need to exist on the local agent yet but a [sidecar proxy - registration](/docs/connect/registration/service-registration) with + registration](/consul/docs/connect/registration/service-registration) with `proxy.destination_service_id` equal to the passed value must be present. If multiple proxy registrations targeting the same local service instance are present the command will error and `-proxy-id` should be used instead. This can also be specified via the `CONNECT_SIDECAR_FOR` environment variable. - `-proxy-id` - The [proxy - service](/docs/connect/registration/service-registration) ID on the + service](/consul/docs/connect/registration/service-registration) ID on the local agent. This must already be present on the local agent. This option can also be specified via the `CONNECT_PROXY_ID` environment variable. @@ -44,7 +44,7 @@ Usage: `consul connect proxy [options]` doesn't need to actually exist in the Consul catalog, but proper ACL permissions (`service:write`) are required. This and the remaining options can be used to setup a proxy that is not registered already with local config - [useful for development](/docs/connect/dev). + [useful for development](/consul/docs/connect/dev). - `-upstream` - Upstream service to support connecting to. The format should be 'name:addr', such as 'db:8181'. This will make 'db' available on port 8181. @@ -66,7 +66,7 @@ Usage: `consul connect proxy [options]` - `-register-id` - Optional ID suffix for the service when `-register` is set to disambiguate the service ID. By default the service ID is `-proxy` where `` is the `-service` value. In most cases it is now preferable - to use [`consul services register`](/commands/services/register) to + to use [`consul services register`](/consul/commands/services/register) to register a fully configured proxy instance rather than specify config and registration via this command. diff --git a/website/content/commands/connect/redirect-traffic.mdx b/website/content/commands/connect/redirect-traffic.mdx index aa87e69ef9..ded81c4a94 100644 --- a/website/content/commands/connect/redirect-traffic.mdx +++ b/website/content/commands/connect/redirect-traffic.mdx @@ -13,7 +13,7 @@ Command: `consul connect redirect-traffic` The connect redirect-traffic command is used to apply traffic redirection rules to enforce all traffic to go through the [Envoy proxy](https://envoyproxy.io) when using [Consul -Service Mesh](/docs/connect/) in the Transparent Proxy mode. +Service Mesh](/consul/docs/connect/) in the Transparent Proxy mode. This command requires `iptables` command line utility to be installed, and as a result, this command can currently only run on linux. @@ -38,7 +38,7 @@ Usage: `consul connect redirect-traffic [options]` - `-consul-dns-port` - The port of the Consul DNS resolver. If provided, DNS queries will be redirected to the provided IP address for name resolution. -- `-proxy-id` - The [proxy service](/docs/connect/registration/service-registration) ID. +- `-proxy-id` - The [proxy service](/consul/docs/connect/registration/service-registration) ID. This service ID must already be registered with the local agent. - `-proxy-inbound-port` - The inbound port that the proxy is listening on. diff --git a/website/content/commands/debug.mdx b/website/content/commands/debug.mdx index 202fefd747..c0755251f0 100644 --- a/website/content/commands/debug.mdx +++ b/website/content/commands/debug.mdx @@ -78,7 +78,7 @@ information when `debug` is running. By default, it captures all information. | `members` | A list of all the WAN and LAN members in the cluster. | | `metrics` | Metrics from the in-memory metrics endpoint in the target, captured at the interval. | | `logs` | `DEBUG` level logs for the target agent, captured for the duration. | -| `pprof` | Golang heap, CPU, goroutine, and trace profiling. CPU and traces are captured for `duration` in a single file while heap and goroutine are separate snapshots for each `interval`. This information is not retrieved unless [`enable_debug`](/docs/agent/config/config-files#enable_debug) is set to `true` on the target agent or ACLs are enable and an ACL token with `operator:read` is provided. | +| `pprof` | Golang heap, CPU, goroutine, and trace profiling. CPU and traces are captured for `duration` in a single file while heap and goroutine are separate snapshots for each `interval`. This information is not retrieved unless [`enable_debug`](/consul/docs/agent/config/config-files#enable_debug) is set to `true` on the target agent or ACLs are enable and an ACL token with `operator:read` is provided. | ## Examples diff --git a/website/content/commands/event.mdx b/website/content/commands/event.mdx index 5850440fb1..d89b71d68c 100644 --- a/website/content/commands/event.mdx +++ b/website/content/commands/event.mdx @@ -13,20 +13,20 @@ description: >- Command: `consul event` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/event/fire/:name](/api-docs/event#fire-event) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/event/fire/:name](/consul/api-docs/event#fire-event) The `event` command provides a mechanism to fire a custom user event to an entire datacenter. These events are opaque to Consul, but they can be used to build scripting infrastructure to do automated deploys, restart services, or perform any other orchestration action. Events can be handled by -[using a watch](/docs/dynamic-app-config/watches). +[using a watch](/consul/docs/dynamic-app-config/watches). -Under the hood, events are propagated using the [gossip protocol](/docs/architecture/gossip). +Under the hood, events are propagated using the [gossip protocol](/consul/docs/architecture/gossip). While the details are not important for using events, an understanding of the semantics is useful. The gossip layer will make a best-effort to deliver the event, but there is **no guaranteed delivery**. Unlike most Consul data, which is -replicated using [consensus](/docs/architecture/consensus), event data +replicated using [consensus](/consul/docs/architecture/consensus), event data is purely peer-to-peer over gossip. This means it is not persisted and does not have a total ordering. In practice, this means you cannot rely on the order of message delivery. An advantage however is that events can still @@ -37,8 +37,8 @@ message. It is hard to give an exact number, as it depends on various parameters of the event, but the payload should be kept very small (< 100 bytes). Specifying too large of an event will return an error. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/exec.mdx b/website/content/commands/exec.mdx index d6abf4b212..a90cdb35df 100644 --- a/website/content/commands/exec.mdx +++ b/website/content/commands/exec.mdx @@ -16,8 +16,8 @@ this can be used to run the `uptime` command across all machines providing the `web` service. Remote execution works by specifying a job, which is stored in the KV store. -Agents are informed about the new job using the [event system](/commands/event), -which propagates messages via the [gossip protocol](/docs/architecture/gossip). +Agents are informed about the new job using the [event system](/consul/commands/event), +which propagates messages via the [gossip protocol](/consul/docs/architecture/gossip). As a result, delivery is best-effort, and there is **no guarantee** of execution. While events are purely gossip driven, remote execution relies on the KV store @@ -30,7 +30,7 @@ through the Consul servers and the Raft consensus algorithm, so having a large number of nodes in the cluster flow a large amount of data through the KV store could make the cluster unavailable. -The table below shows the [required ACLs](/api-docs/api-structure#authentication) in order to +The table below shows the [required ACLs](/consul/api-docs/api-structure#authentication) in order to execute this command. | ACL Required | Scope | @@ -40,7 +40,7 @@ execute this command. | `key:write` | `"_rexec"` prefix | | `event:write` | `"_rexec"` prefix | -In addition to the above, the policy associated with the [agent token](/docs/security/acl/acl-tokens#acl-agent-token) should have `write` on `"_rexec"` key prefix. This is for the agents to read the `exec` command and write its output back to the KV store. +In addition to the above, the policy associated with the [agent token](/consul/docs/security/acl/acl-tokens#acl-agent-token) should have `write` on `"_rexec"` key prefix. This is for the agents to read the `exec` command and write its output back to the KV store. ## Usage diff --git a/website/content/commands/force-leave.mdx b/website/content/commands/force-leave.mdx index 57f674ce71..f535e4d003 100644 --- a/website/content/commands/force-leave.mdx +++ b/website/content/commands/force-leave.mdx @@ -11,17 +11,17 @@ description: >- Command: `consul force-leave` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/force-leave/:node](/api-docs/agent#force-leave-and-shutdown) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/force-leave/:node](/consul/api-docs/agent#force-leave-and-shutdown) The `force-leave` command forces a member of a Consul cluster to enter the "left" state. The purpose of this method is to force-remove a node that has failed or -was shutdown without a [graceful leave](/commands/leave). +was shutdown without a [graceful leave](/consul/commands/leave). Consul periodically tries to reconnect to "failed" nodes in case failure was due to a network partition. After some configured amount of time (by default 72 hours), Consul will reap "failed" nodes and stop trying to reconnect. The `force-leave` command can be used to transition the "failed" nodes to a "left" state more -quickly, as reported by [`consul members`](/commands/members). +quickly, as reported by [`consul members`](/consul/commands/members). This can be particularly useful for a node that was running as a server, as it will eventually be removed from the Raft configuration by the leader. @@ -32,8 +32,8 @@ from the datacenter's member list nor from the raft configuration. Additionally, if the agent returns after transitioning to the "left" state, but before it is reaped from the member list, then it will rejoin the cluster. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/index.mdx b/website/content/commands/index.mdx index 7f6ddb0bb4..2946d794ba 100644 --- a/website/content/commands/index.mdx +++ b/website/content/commands/index.mdx @@ -94,8 +94,8 @@ Command Options ## Authentication -When the [ACL system is enabled](/docs/agent/config/config-files#acl) the Consul CLI will -require an [ACL token](/docs/security/acl#tokens) to perform API requests. +When the [ACL system is enabled](/consul/docs/agent/config/config-files#acl) the Consul CLI will +require an [ACL token](/consul/docs/security/acl#tokens) to perform API requests. The ACL token can be provided directly on the command line using the `-token` command line flag, from a file using the `-token-file` command line flag, or from the @@ -123,7 +123,7 @@ list-peers remove-peer ## Arguments with URL-Invalid Characters The CLI automatically URL-encodes arguments, which are then -[URL-decoded by the underlying HTTP API endpoints](/api-docs/api-structure#url-encoded-resource-names). +[URL-decoded by the underlying HTTP API endpoints](/consul/api-docs/api-structure#url-encoded-resource-names). To avoid double-encoding arguments, do not URL-encode arguments passed to the CLI. ## Environment Variables @@ -241,8 +241,8 @@ CONSUL_TLS_SERVER_NAME=consulserver.domain Like [`CONSUL_HTTP_ADDR`](#consul_http_addr) but configures the address the local agent is listening for gRPC requests. Currently gRPC is only used for -integrating [Envoy proxy](/docs/connect/proxies/envoy) and must be [enabled -explicitly](/docs/agent/config/config-files#grpc_port) in agent configuration. +integrating [Envoy proxy](/consul/docs/connect/proxies/envoy) and must be [enabled +explicitly](/consul/docs/agent/config/config-files#grpc_port) in agent configuration. ``` CONSUL_GRPC_ADDR=127.0.0.1:8502 @@ -255,7 +255,7 @@ CONSUL_GRPC_ADDR=unix://var/run/consul_grpc.sock ``` If the agent is [configured with TLS -certificates](/docs/security/encryption#rpc-encryption-with-tls), then the +certificates](/consul/docs/security/encryption#rpc-encryption-with-tls), then the gRPC listener will require TLS and present the same certificate as the https listener. As with `CONSUL_HTTP_ADDR`, if TLS is enabled either the `https://` scheme should be used, or `CONSUL_HTTP_SSL` set. diff --git a/website/content/commands/info.mdx b/website/content/commands/info.mdx index 3ffb69556f..0a74422f58 100644 --- a/website/content/commands/info.mdx +++ b/website/content/commands/info.mdx @@ -19,9 +19,9 @@ There are currently the top-level keys for: - agent: Provides information about the agent - consul: Information about the consul library (client or server) -- raft: Provides info about the Raft [consensus library](/docs/architecture/consensus) -- serf_lan: Provides info about the LAN [gossip pool](/docs/architecture/gossip) -- serf_wan: Provides info about the WAN [gossip pool](/docs/architecture/gossip) +- raft: Provides info about the Raft [consensus library](/consul/docs/architecture/consensus) +- serf_lan: Provides info about the LAN [gossip pool](/consul/docs/architecture/gossip) +- serf_wan: Provides info about the WAN [gossip pool](/consul/docs/architecture/gossip) Here is an example output: diff --git a/website/content/commands/intention/check.mdx b/website/content/commands/intention/check.mdx index 8fc7a48706..4c2f64c97e 100644 --- a/website/content/commands/intention/check.mdx +++ b/website/content/commands/intention/check.mdx @@ -7,7 +7,7 @@ page_title: 'Commands: Intention Check' Command: `consul intention check` -Corresponding HTTP API Endpoint: [\[GET\] /v1/connect/intentions/check](/api-docs/connect/intentions#check-intention-result) +Corresponding HTTP API Endpoint: [\[GET\] /v1/connect/intentions/check](/consul/api-docs/connect/intentions#check-intention-result) The `intention check` command checks whether a connection attempt between two services would be authorized given the current set of intentions and @@ -16,15 +16,15 @@ Consul configuration. This command requires less ACL permissions than other intention-related tasks because no information about the intention is revealed. Therefore, callers only need to have `service:read` access for the destination. Richer -commands like [match](/commands/intention/match) require full +commands like [match](/consul/commands/intention/match) require full intention read permissions and don't evaluate the result. -> **Note:** This command will always treat intentions with `Permissions` defined as _deny_ intentions during evaluation, as this endpoint is only suited for networking layer 4 (e.g. TCP) integration. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -44,7 +44,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint Usage: `consul intention check [options] SRC DST` -`SRC` and `DST` can both take [several forms](/commands/intention#source-and-destination-naming). +`SRC` and `DST` can both take [several forms](/consul/commands/intention#source-and-destination-naming). #### Enterprise Options diff --git a/website/content/commands/intention/create.mdx b/website/content/commands/intention/create.mdx index b81ba49dfa..cae1927ee5 100644 --- a/website/content/commands/intention/create.mdx +++ b/website/content/commands/intention/create.mdx @@ -6,19 +6,19 @@ page_title: 'Commands: Intention Create' # Consul Intention Create -> **Deprecated** - This command is deprecated in Consul 1.9.0 in favor of -using the [config entry CLI command](/commands/config/write). To create an +using the [config entry CLI command](/consul/commands/config/write). To create an intention, create or modify a -[`service-intentions`](/docs/connect/config-entries/service-intentions) config +[`service-intentions`](/consul/docs/connect/config-entries/service-intentions) config entry for the destination. Command: `consul intention create` -Corresponding HTTP API Endpoint: [\[POST\] /v1/connect/intentions](/api-docs/connect/intentions#create-intention-with-id) +Corresponding HTTP API Endpoint: [\[POST\] /v1/connect/intentions](/consul/api-docs/connect/intentions#create-intention-with-id) The `intention create` command creates or updates an L4 intention. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -39,7 +39,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint - `consul intention create [options] SRC DST` - `consul intention create [options] -file FILE...` -`SRC` and `DST` can both take [several forms](/commands/intention#source-and-destination-naming). +`SRC` and `DST` can both take [several forms](/consul/commands/intention#source-and-destination-naming). #### Command Options diff --git a/website/content/commands/intention/delete.mdx b/website/content/commands/intention/delete.mdx index 136e5e5ae8..aa68a769fa 100644 --- a/website/content/commands/intention/delete.mdx +++ b/website/content/commands/intention/delete.mdx @@ -7,12 +7,12 @@ page_title: 'Commands: Intention Delete' Command: `consul intention delete` -Corresponding HTTP API Endpoints: [\[DELETE\] /v1/connect/intentions/exact](/api-docs/connect/intentions#delete-intention-by-name), [\[DELETE\] /v1/connect/intentions/:uuid](/api-docs/connect/intentions#delete-intention-by-id) +Corresponding HTTP API Endpoints: [\[DELETE\] /v1/connect/intentions/exact](/consul/api-docs/connect/intentions#delete-intention-by-name), [\[DELETE\] /v1/connect/intentions/:uuid](/consul/api-docs/connect/intentions#delete-intention-by-id) The `intention delete` command deletes a matching intention. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -30,7 +30,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint -> **Deprecated** - The one argument form of this command is deprecated in Consul 1.9.0. Intentions no longer need IDs when represented as -[`service-intentions`](/docs/connect/config-entries/service-intentions) config +[`service-intentions`](/consul/docs/connect/config-entries/service-intentions) config entries. ## Usage @@ -40,7 +40,7 @@ Usage: - `consul intention delete [options] SRC DST` - `consul intention delete [options] ID` -`SRC` and `DST` can both take [several forms](/commands/intention#source-and-destination-naming). +`SRC` and `DST` can both take [several forms](/consul/commands/intention#source-and-destination-naming). #### Enterprise Options diff --git a/website/content/commands/intention/get.mdx b/website/content/commands/intention/get.mdx index 3da1688f6e..c4157d8544 100644 --- a/website/content/commands/intention/get.mdx +++ b/website/content/commands/intention/get.mdx @@ -7,17 +7,17 @@ page_title: 'Commands: Intention Get' Command: `consul intention get` -Corresponding HTTP API Endpoints: [\[GET\] /v1/connect/intentions/exact](/api-docs/connect/intentions#read-specific-intention-by-name), [\[GET\] /v1/connect/intentions/:uuid](/api-docs/connect/intentions#read-specific-intention-by-id) +Corresponding HTTP API Endpoints: [\[GET\] /v1/connect/intentions/exact](/consul/api-docs/connect/intentions#read-specific-intention-by-name), [\[GET\] /v1/connect/intentions/:uuid](/consul/api-docs/connect/intentions#read-specific-intention-by-id) The `intention get` command shows a single intention. -> **Deprecated** - The one argument form of this command is deprecated in Consul 1.9.0. Intentions no longer need IDs when represented as -[`service-intentions`](/docs/connect/config-entries/service-intentions) config +[`service-intentions`](/consul/docs/connect/config-entries/service-intentions) config entries. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -40,7 +40,7 @@ Usage: - `consul intention get [options] SRC DST` - `consul intention get [options] ID` -`SRC` and `DST` can both take [several forms](/commands/intention#source-and-destination-naming). +`SRC` and `DST` can both take [several forms](/consul/commands/intention#source-and-destination-naming). #### Enterprise Options diff --git a/website/content/commands/intention/index.mdx b/website/content/commands/intention/index.mdx index b907d144ba..5f9b2fb328 100644 --- a/website/content/commands/intention/index.mdx +++ b/website/content/commands/intention/index.mdx @@ -8,19 +8,19 @@ page_title: 'Commands: Intention' Command: `consul intention` The `intention` command is used to interact with Connect -[intentions](/docs/connect/intentions). It exposes commands for +[intentions](/consul/docs/connect/intentions). It exposes commands for creating, updating, reading, deleting, checking, and managing intentions. This command is available in Consul 1.2 and later. Intentions are managed primarily via -[`service-intentions`](/docs/connect/config-entries/service-intentions) config +[`service-intentions`](/consul/docs/connect/config-entries/service-intentions) config entries after Consul 1.9. Intentions may also be managed via the [HTTP -API](/api-docs/connect/intentions). +API](/consul/api-docs/connect/intentions). ~> **Deprecated** - This command is deprecated in Consul 1.9.0 in favor of -using the [config entry CLI command](/commands/config/write). To create an +using the [config entry CLI command](/consul/commands/config/write). To create an intention, create or modify a -[`service-intentions`](/docs/connect/config-entries/service-intentions) config +[`service-intentions`](/consul/docs/connect/config-entries/service-intentions) config entry for the destination. ## Usage diff --git a/website/content/commands/intention/list.mdx b/website/content/commands/intention/list.mdx index 9748494b8f..ea96b34ba7 100644 --- a/website/content/commands/intention/list.mdx +++ b/website/content/commands/intention/list.mdx @@ -7,12 +7,12 @@ page_title: 'Commands: Intention List' Command: `consul intention list` -Corresponding HTTP API Endpoint: [\[GET\] /v1/connect/intentions](/api-docs/connect/intentions#list-intentions) +Corresponding HTTP API Endpoint: [\[GET\] /v1/connect/intentions](/consul/api-docs/connect/intentions#list-intentions) The `intention list` command shows all intentions including ID and precedence. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/intention/match.mdx b/website/content/commands/intention/match.mdx index ee41469249..8b5448a2ac 100644 --- a/website/content/commands/intention/match.mdx +++ b/website/content/commands/intention/match.mdx @@ -7,17 +7,17 @@ page_title: 'Commands: Intention Match' Command: `consul intention match` -Corresponding HTTP API Endpoint: [\[GET\] /v1/connect/intentions/match](/api-docs/connect/intentions#list-matching-intentions) +Corresponding HTTP API Endpoint: [\[GET\] /v1/connect/intentions/match](/consul/api-docs/connect/intentions#list-matching-intentions) The `intention match` command shows the list of intentions that match a given source or destination. The list of intentions is listed in evaluation order: the first intention that matches a request would be evaluated. -The [check](/commands/intention/check) command can be used to +The [check](/consul/commands/intention/check) command can be used to check whether an L4 connection would be authorized between any two services. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -37,7 +37,7 @@ are not supported from commands, but may be from the corresponding HTTP endpoint Usage: `consul intention match [options] SRC_OR_DST` -`SRC` and `DST` can both take [several forms](/commands/intention#source-and-destination-naming). +`SRC` and `DST` can both take [several forms](/consul/commands/intention#source-and-destination-naming). #### Command Options diff --git a/website/content/commands/join.mdx b/website/content/commands/join.mdx index 600e12d5e6..7bb438911d 100644 --- a/website/content/commands/join.mdx +++ b/website/content/commands/join.mdx @@ -12,7 +12,7 @@ description: >- Command: `consul join` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/join/:address](/api-docs/agent#join-agent) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/join/:address](/consul/api-docs/agent#join-agent) The `join` command tells a Consul agent to join an existing cluster. A new Consul agent may join any node in the existing cluster. After joining @@ -22,8 +22,8 @@ state across the cluster. An agent which is already part of a cluster may join an agent in a different cluster, causing the two clusters to be merged into a single cluster. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/keygen.mdx b/website/content/commands/keygen.mdx index 15ba9418db..c512eeef53 100644 --- a/website/content/commands/keygen.mdx +++ b/website/content/commands/keygen.mdx @@ -12,6 +12,6 @@ description: >- Command: `consul keygen` The `keygen` command generates an encryption key that can be used for -[Consul agent traffic encryption](/docs/security/encryption). +[Consul agent traffic encryption](/consul/docs/security/encryption). The keygen command uses a cryptographically strong pseudo-random number generator to generate the key. diff --git a/website/content/commands/keyring.mdx b/website/content/commands/keyring.mdx index 9c5aecaaf1..8c7b2d0e1c 100644 --- a/website/content/commands/keyring.mdx +++ b/website/content/commands/keyring.mdx @@ -7,10 +7,10 @@ page_title: 'Commands: Keyring' Command: `consul keyring` -Corresponding HTTP API Endpoints: [\[VARIES\] /v1/operator/keyring](/api-docs/operator/keyring) +Corresponding HTTP API Endpoints: [\[VARIES\] /v1/operator/keyring](/consul/api-docs/operator/keyring) The `keyring` command is used to examine and modify the encryption keys used in -Consul's [Gossip Pools](/docs/architecture/gossip). It is capable of +Consul's [Gossip Pools](/consul/docs/architecture/gossip). It is capable of distributing new encryption keys to the cluster, retiring old encryption keys, and changing the keys used by the cluster to encrypt messages. @@ -29,8 +29,8 @@ All variations of the `keyring` command return 0 if all nodes reply and there are no errors. If any node fails to reply or reports failure, the exit code will be 1. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required1 | diff --git a/website/content/commands/kv/delete.mdx b/website/content/commands/kv/delete.mdx index c4ea987168..b01d34af46 100644 --- a/website/content/commands/kv/delete.mdx +++ b/website/content/commands/kv/delete.mdx @@ -7,13 +7,13 @@ page_title: 'Commands: KV Delete' Command: `consul kv delete` -Corresponding HTTP API Endpoint: [\[DELETE\] /v1/kv/:key](/api-docs/kv#delete-key) +Corresponding HTTP API Endpoint: [\[DELETE\] /v1/kv/:key](/consul/api-docs/kv#delete-key) The `kv delete` command removes the value from Consul's KV store at the given path. If no key exists at the path, no action is taken. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/kv/export.mdx b/website/content/commands/kv/export.mdx index 13dbb1d6d5..bb7750d16e 100644 --- a/website/content/commands/kv/export.mdx +++ b/website/content/commands/kv/export.mdx @@ -12,8 +12,8 @@ prefix from Consul's KV store, and write a JSON representation to stdout. This can be used with the command "consul kv import" to move entire trees between Consul clusters. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/kv/get.mdx b/website/content/commands/kv/get.mdx index 5b8ec9222d..47abec4d43 100644 --- a/website/content/commands/kv/get.mdx +++ b/website/content/commands/kv/get.mdx @@ -7,7 +7,7 @@ page_title: 'Commands: KV Get' Command: `consul kv get` -Corresponding HTTP API Endpoint: [\[GET\] /v1/kv/:key](/api-docs/kv#read-key) +Corresponding HTTP API Endpoint: [\[GET\] /v1/kv/:key](/consul/api-docs/kv#read-key) The `kv get` command is used to retrieve the value from Consul's KV store at the given key name. If no key exists with that name, an error is @@ -15,13 +15,13 @@ returned. If a key exists with that name but has no data, nothing is returned. A key name or prefix is required. -> **Note**: When reading many entries under a given prefix, it may be worth -considering [`kv export`](/commands/kv/export) instead. The kv export output -can be used with [`kv import`](/commands/kv/import) to move entire trees between -Consul clusters. Alternatively, the [transaction API](/api-docs/txn) provides +considering [`kv export`](/consul/commands/kv/export) instead. The kv export output +can be used with [`kv import`](/consul/commands/kv/import) to move entire trees between +Consul clusters. Alternatively, the [transaction API](/consul/api-docs/txn) provides support for performing up to 64 KV operations atomically. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/kv/import.mdx b/website/content/commands/kv/import.mdx index 8fef56f37c..37d99db0fa 100644 --- a/website/content/commands/kv/import.mdx +++ b/website/content/commands/kv/import.mdx @@ -10,8 +10,8 @@ Command: `consul kv import` The `kv import` command is used to import KV pairs from the JSON representation generated by the `kv export` command. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/kv/index.mdx b/website/content/commands/kv/index.mdx index 49bfcc6b47..7e6a8202af 100644 --- a/website/content/commands/kv/index.mdx +++ b/website/content/commands/kv/index.mdx @@ -13,7 +13,7 @@ and deleting from the store. This command is available in Consul 0.7.1 and later. The KV store is also accessible via the -[HTTP API](/api-docs/kv). +[HTTP API](/consul/api-docs/kv). ## Usage @@ -39,11 +39,11 @@ Subcommands: For more information, examples, and usage about a subcommand, click on the name of the subcommand in the sidebar or one of the links below: -- [delete](/commands/kv/delete) -- [export](/commands/kv/export) -- [get](/commands/kv/get) -- [import](/commands/kv/import) -- [put](/commands/kv/put) +- [delete](/consul/commands/kv/delete) +- [export](/consul/commands/kv/export) +- [get](/consul/commands/kv/get) +- [import](/consul/commands/kv/import) +- [put](/consul/commands/kv/put) ## Basic Examples diff --git a/website/content/commands/kv/put.mdx b/website/content/commands/kv/put.mdx index 2553c3d594..3903ac6be3 100644 --- a/website/content/commands/kv/put.mdx +++ b/website/content/commands/kv/put.mdx @@ -7,17 +7,17 @@ page_title: 'Commands: KV Put' Command: `consul kv put` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/kv/:key](/api-docs/kv#create-update-key) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/kv/:key](/consul/api-docs/kv#create-update-key) The `kv put` command writes the data to the given path in the KV store. -> **Note**: When writing multiple entries at once, consider using -[`kv import`](/commands/kv/import) instead. Alternatively, the -[transaction API](/api-docs/txn) provides support for performing up to +[`kv import`](/consul/commands/kv/import) instead. Alternatively, the +[transaction API](/consul/api-docs/txn) provides support for performing up to 64 KV operations atomically. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -132,7 +132,7 @@ Success! Data written to: leaderboard/scores ``` ~> **Warning**: For secret and sensitive values, you should consider using a -secret management solution like **[HashiCorp's Vault](https://learn.hashicorp.com/tutorials/vault/static-secrets?in=vault/secrets-management)**. +secret management solution like **[HashiCorp's Vault](/vault/tutorials/secrets-management/static-secrets)**. While it is possible to encrypt data before writing it to Consul's KV store, Consul provides no built-in support for encryption at-rest. @@ -170,7 +170,7 @@ Success! Lock released on: redis/lock/update ~> **Warning!** If you are trying to build a locking mechanism with these low-level primitives, you may want to look at the [consul -lock](/commands/lock) command. It provides higher-level +lock](/consul/commands/lock) command. It provides higher-level functionality without exposing the internal APIs of Consul. ### Flags diff --git a/website/content/commands/leave.mdx b/website/content/commands/leave.mdx index 0862c03a9d..3dccedc7cc 100644 --- a/website/content/commands/leave.mdx +++ b/website/content/commands/leave.mdx @@ -11,7 +11,7 @@ description: >- Command: `consul leave` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/leave](/api-docs/agent#graceful-leave-and-shutdown) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/leave](/consul/api-docs/agent#graceful-leave-and-shutdown) The `leave` command triggers a graceful leave and shutdown of the agent. It is used to ensure other nodes see the agent as "left" instead of @@ -25,8 +25,8 @@ non-graceful leave can affect cluster availability. Running `consul leave` on a server explicitly will reduce the quorum size. Even if the cluster used `bootstrap_expect` to set a quorum size initially, issuing `consul leave` on a server will reconfigure the cluster to have fewer servers. This means you could end up with just one server that is still able to commit writes because quorum is only 1, but those writes might be lost if that server fails before more are added. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/license.mdx b/website/content/commands/license.mdx index 4a4887cf8c..50cee37544 100644 --- a/website/content/commands/license.mdx +++ b/website/content/commands/license.mdx @@ -15,13 +15,13 @@ Command: `consul license` The `license` command provides a list of all datacenters that use the Consul Enterprise license applied to the current datacenter. ~> **Warning**: Consul 1.10.0 removed the ability to set and reset the license using the CLI. -See the [licensing documentation](/docs/enterprise/license/overview) for more information about +See the [licensing documentation](/consul/docs/enterprise/license/overview) for more information about Consul Enterprise license management. If ACLs are enabled then a token with operator privileges may be required in order to use this command. Requests are forwarded internally to the leader if required, so this can be run from any Consul node in a cluster. See the -[ACL Guide](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) for more information. +[ACL Guide](/consul/tutorials/security/access-control-setup-production) for more information. ```text Usage: consul license [options] [args] @@ -125,12 +125,12 @@ License is valid was removed in Consul 1.10. While the CLI command still exists it will always return an error. This command will be fully removed in a future release. -Corresponding HTTP API Endpoint: [\[PUT\] /v1/operator/license](/api-docs/operator/license#updating-the-consul-license) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/operator/license](/consul/api-docs/operator/license#updating-the-consul-license) This command sets the Consul Enterprise license. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -165,12 +165,12 @@ Licensed Features: ## get -Corresponding HTTP API Endpoint: [\[GET\] /v1/operator/license](/api-docs/operator/license#getting-the-consul-license) +Corresponding HTTP API Endpoint: [\[GET\] /v1/operator/license](/consul/api-docs/operator/license#getting-the-consul-license) This command gets the Consul Enterprise license. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -209,13 +209,13 @@ Licensed Features: was removed in Consul 1.10. While the CLI command still exists it will always return an error. This command will be fully removed in a future release. -Corresponding HTTP API Endpoint: [\[DELETE\] /v1/operator/license](/api-docs/operator/license#resetting-the-consul-license) +Corresponding HTTP API Endpoint: [\[DELETE\] /v1/operator/license](/consul/api-docs/operator/license#resetting-the-consul-license) Resets license for the datacenter to the one builtin in Consul binary, if it is still valid. If the builtin license is invalid, the current one stays active. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/lock.mdx b/website/content/commands/lock.mdx index fb80f65547..ad69cb9be3 100644 --- a/website/content/commands/lock.mdx +++ b/website/content/commands/lock.mdx @@ -18,7 +18,7 @@ communication is disrupted, the child process is terminated. The number of lock holders is configurable with the `-n` flag. By default, a single holder is allowed, and a lock is used for mutual exclusion. This -uses the [leader election algorithm](https://learn.hashicorp.com/tutorials/consul/application-leader-elections). +uses the [leader election algorithm](/consul/tutorials/developer-configuration/application-leader-elections). If the lock holder count is more than one, then a semaphore is used instead. A semaphore allows more than a single holder, but this is less efficient than diff --git a/website/content/commands/login.mdx b/website/content/commands/login.mdx index 48d5783458..b5ec3c11cb 100644 --- a/website/content/commands/login.mdx +++ b/website/content/commands/login.mdx @@ -10,15 +10,15 @@ description: > Command: `consul login` -Corresponding HTTP API Endpoint: [\[POST\] /v1/acl/login](/api-docs/acl#login-to-auth-method) +Corresponding HTTP API Endpoint: [\[POST\] /v1/acl/login](/consul/api-docs/acl#login-to-auth-method) The `login` command will exchange the provided third party credentials with the requested auth method for a newly minted Consul ACL token. The companion command `consul logout` should be used to destroy any tokens created this way to avoid a resource leak. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/logout.mdx b/website/content/commands/logout.mdx index 6f4ce7e448..3153936404 100644 --- a/website/content/commands/logout.mdx +++ b/website/content/commands/logout.mdx @@ -10,13 +10,13 @@ description: > Command: `consul logout` -Corresponding HTTP API Endpoint: [\[POST\] /v1/acl/logout](/api-docs/acl#logout-from-auth-method) +Corresponding HTTP API Endpoint: [\[POST\] /v1/acl/logout](/consul/api-docs/acl#logout-from-auth-method) The `logout` command will destroy the provided token if it was created from `consul login`. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/maint.mdx b/website/content/commands/maint.mdx index cdd953694c..387c366821 100644 --- a/website/content/commands/maint.mdx +++ b/website/content/commands/maint.mdx @@ -9,7 +9,7 @@ description: | Command: `consul maint` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/maintenance](/api-docs/agent#enable-maintenance-mode) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/maintenance](/consul/api-docs/agent#enable-maintenance-mode) The `maint` command provides control of service maintenance mode. Using the command, it is possible to mark a service provided by a node or all the services on the @@ -21,8 +21,8 @@ Under the hood, maintenance mode is activated by registering a health check in critical status against a service, and deactivated by deregistering the health check. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/members.mdx b/website/content/commands/members.mdx index a8dd69d1fc..4e6b73cae2 100644 --- a/website/content/commands/members.mdx +++ b/website/content/commands/members.mdx @@ -11,7 +11,7 @@ description: >- Command: `consul members` -Corresponding HTTP API Endpoint: [\[GET\] /v1/agent/members](/api-docs/agent#list-members) +Corresponding HTTP API Endpoint: [\[GET\] /v1/agent/members](/consul/api-docs/agent#list-members) The `members` command outputs the current list of members that a Consul agent knows about, along with their state. The state of a node can only @@ -21,8 +21,8 @@ Nodes in the "failed" state are still listed because Consul attempts to reconnect with failed nodes for a certain amount of time in the case that the failure is actually just a network partition. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/namespace/create.mdx b/website/content/commands/namespace/create.mdx index a1aebb82d0..887ee1d704 100644 --- a/website/content/commands/namespace/create.mdx +++ b/website/content/commands/namespace/create.mdx @@ -7,15 +7,15 @@ page_title: 'Commands: Namespace Create' Command: `consul namespace create` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/namespace](/api-docs/namespaces#create-a-namespace) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/namespace](/consul/api-docs/namespaces#create-a-namespace) This `namespace create` command creates a namespaces using the CLI parameters provided. This was added in Consul Enterprise 1.7.2. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -36,11 +36,11 @@ from the CLI arguments. - `-default-policy-name=` - Name of a policy from the default namespace to inject for all tokens in this namespace. May be specified multiple times. The ACL token used with - this command must have [`acl:write` access](/docs/security/acl/acl-rules#acl-resource-rules) to the linked policy. + this command must have [`acl:write` access](/consul/docs/security/acl/acl-rules#acl-resource-rules) to the linked policy. - `-default-role-id=` - ID of a role from the default namespace to inject for all tokens in this namespace. May be specified multiple times. The ACL token used with - this command must have [`acl:write` access](/docs/security/acl/acl-rules#acl-resource-rules) to the linked role. + this command must have [`acl:write` access](/consul/docs/security/acl/acl-rules#acl-resource-rules) to the linked role. - `-default-role-name=` - Name of a role from the default namespace to inject for all tokens in this namespace. May be specified multiple times. diff --git a/website/content/commands/namespace/delete.mdx b/website/content/commands/namespace/delete.mdx index 9c158324ff..960e2f46d7 100644 --- a/website/content/commands/namespace/delete.mdx +++ b/website/content/commands/namespace/delete.mdx @@ -7,15 +7,15 @@ page_title: 'Commands: Namespace Delete' Command: `consul namespace delete` -Corresponding HTTP API Endpoint: [\[DELETE\] /v1/namespace/:name](/api-docs/namespaces#delete-a-namespace) +Corresponding HTTP API Endpoint: [\[DELETE\] /v1/namespace/:name](/consul/api-docs/namespaces#delete-a-namespace) This `namespace delete` command deletes a namespace. This was added in Consul Enterprise 1.7.0. If ACLs are enabled then this command will require a token with `operator:write` privileges. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/namespace/list.mdx b/website/content/commands/namespace/list.mdx index 3228a04049..0070ab0228 100644 --- a/website/content/commands/namespace/list.mdx +++ b/website/content/commands/namespace/list.mdx @@ -7,7 +7,7 @@ page_title: 'Commands: Namespace List' Command: `consul namespace list` -Corresponding HTTP API Endpoint: [\[GET\] /v1/namespaces](/api-docs/namespaces#list-all-namespaces) +Corresponding HTTP API Endpoint: [\[GET\] /v1/namespaces](/consul/api-docs/namespaces#list-all-namespaces) @@ -16,8 +16,8 @@ ACLs are enabled then this command will require a token with `operator:read` pri within the target namespaces. The results will be filtered based on the ACL token and therefore it is possible to see a partial list. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/namespace/read.mdx b/website/content/commands/namespace/read.mdx index 45324851b9..4aaf8c5add 100644 --- a/website/content/commands/namespace/read.mdx +++ b/website/content/commands/namespace/read.mdx @@ -7,7 +7,7 @@ page_title: 'Commands: Namespace Read' Command: `consul namespace read` -Corresponding HTTP API Endpoint: [\[GET\] /v1/namespace/:name](/api-docs/namespaces#read-a-namespace) +Corresponding HTTP API Endpoint: [\[GET\] /v1/namespace/:name](/consul/api-docs/namespaces#read-a-namespace) @@ -15,8 +15,8 @@ This `namespace read` command reads a namespaces configuration. This was added i ACLs are enabled then this command will require a token with `operator:read` privileges or any `read` privileges within the target namespace. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/namespace/update.mdx b/website/content/commands/namespace/update.mdx index adc7be00e1..3872d792fa 100644 --- a/website/content/commands/namespace/update.mdx +++ b/website/content/commands/namespace/update.mdx @@ -7,15 +7,15 @@ page_title: 'Commands: Namespace Update' Command: `consul namespace update` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/namespace/:name](/api-docs/namespaces#update-a-namespace) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/namespace/:name](/consul/api-docs/namespaces#update-a-namespace) This `namespace update` command updates a namespaces using the CLI parameters provided. This was added in Consul Enterprise 1.7.2. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -34,19 +34,19 @@ with the existing namespace definition. - `-default-policy-id=` - ID of a policy from the default namespace to inject for all tokens in this namespace. May be specified multiple times. The ACL token used with - this command must have [`acl:write` access](/docs/security/acl/acl-rules#acl-resource-rules) to the linked policy. + this command must have [`acl:write` access](/consul/docs/security/acl/acl-rules#acl-resource-rules) to the linked policy. - `-default-policy-name=` - Name of a policy from the default namespace to inject for all tokens in this namespace. May be specified multiple times. The ACL token used with - this command must have [`acl:write` access](/docs/security/acl/acl-rules#acl-resource-rules) to the linked policy. + this command must have [`acl:write` access](/consul/docs/security/acl/acl-rules#acl-resource-rules) to the linked policy. - `-default-role-id=` - ID of a role from the default namespace to inject for all tokens in this namespace. May be specified multiple times. The ACL token used with - this command must have [`acl:write` access](/docs/security/acl/acl-rules#acl-resource-rules) to the linked role. + this command must have [`acl:write` access](/consul/docs/security/acl/acl-rules#acl-resource-rules) to the linked role. - `-default-role-name=` - Name of a role from the default namespace to inject for all tokens in this namespace. May be specified multiple times. The ACL token used with - this command must have [`acl:write` access](/docs/security/acl/acl-rules#acl-resource-rules) to the linked role. + this command must have [`acl:write` access](/consul/docs/security/acl/acl-rules#acl-resource-rules) to the linked role. - `-description=` - A description of the namespace. diff --git a/website/content/commands/namespace/write.mdx b/website/content/commands/namespace/write.mdx index 90499311f9..b1bc02a8b2 100644 --- a/website/content/commands/namespace/write.mdx +++ b/website/content/commands/namespace/write.mdx @@ -7,14 +7,14 @@ page_title: 'Commands: Namespace Write' Command: `consul namespace write` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/namespace/:name](/api-docs/namespaces#update-a-namespace) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/namespace/:name](/consul/api-docs/namespaces#update-a-namespace) This `namespace write` command creates or updates a namespace's configuration from its full definition. This was added in Consul Enterprise 1.7.0. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -27,7 +27,7 @@ Usage: `consul namespace write ` The `` must either be a file path or `-` to indicate that the definition should be read from stdin. The definition can be in either JSON -or HCL format. See [here](/docs/enterprise/namespaces#namespace-definition) for a description of the namespace definition. +or HCL format. See [here](/consul/docs/enterprise/namespaces#namespace-definition) for a description of the namespace definition. #### Command Options diff --git a/website/content/commands/operator/area.mdx b/website/content/commands/operator/area.mdx index b0be0e101a..0b5525c714 100644 --- a/website/content/commands/operator/area.mdx +++ b/website/content/commands/operator/area.mdx @@ -21,7 +21,7 @@ and relationships can be made between independent pairs of datacenters, so not a need to be fully connected. This allows for complex topologies among Consul datacenters like hub/spoke and more general trees. -See the [Network Areas Guide](https://learn.hashicorp.com/tutorials/consul/federation-network-areas) for more details. +See the [Network Areas Guide](/consul/tutorials/datacenter-operations/federation-network-areas) for more details. ```text Usage: consul operator area [options] @@ -47,12 +47,12 @@ read or write privileges to use these commands. ## create -Corresponding HTTP API Endpoint: [\[POST\] /v1/operator/area](/api-docs/operator/area#create-network-area) +Corresponding HTTP API Endpoint: [\[POST\] /v1/operator/area](/consul/api-docs/operator/area#create-network-area) This command creates a new network area. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -89,12 +89,12 @@ The return code indicates success or failure. ## delete -Corresponding HTTP API Endpoint: [\[DELETE\] /v1/operator/area/:uuid](/api-docs/operator/area#delete-network-area) +Corresponding HTTP API Endpoint: [\[DELETE\] /v1/operator/area/:uuid](/consul/api-docs/operator/area#delete-network-area) This command deletes an existing network area. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -127,13 +127,13 @@ The return code indicates success or failure. ## join -Corresponding HTTP API Endpoint: [\[PUT\] /v1/operator/area/:uuid/join](/api-docs/operator/area#join-network-area) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/operator/area/:uuid/join](/consul/api-docs/operator/area#join-network-area) This command joins Consul servers into an existing network area by address, such as an IP or hostname with an optional port. Multiple addresses may be given. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -172,12 +172,12 @@ The return code indicates success or failure. ## list -Corresponding HTTP API Endpoint: [\[GET\] /v1/operator/area](/api-docs/operator/area#list-network-areas) +Corresponding HTTP API Endpoint: [\[GET\] /v1/operator/area](/consul/api-docs/operator/area#list-network-areas) This command lists all network areas. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -210,13 +210,13 @@ The return code indicates success or failure. ## members -Corresponding HTTP API Endpoint: [\[GET\] /v1/operator/area/:uuid/members](/api-docs/operator/area#list-network-area-members) +Corresponding HTTP API Endpoint: [\[GET\] /v1/operator/area/:uuid/members](/consul/api-docs/operator/area#list-network-area-members) This command displays Consul server nodes present in a network area, or all areas if no area is specified. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -248,14 +248,14 @@ server over its server RPC interface. `Build` has the Consul version running on the node. -`Protocol` is the [protocol version](/docs/upgrading#protocol-versions) being +`Protocol` is the [protocol version](/consul/docs/upgrading#protocol-versions) being spoken by the node. `DC` is the node's Consul datacenter. `RTT` is an estimated network round trip time from the server answering the query to the given server, in a human-readable format. This is computed using -[network coordinates](/docs/architecture/coordinates). +[network coordinates](/consul/docs/architecture/coordinates). The return code indicates success or failure. @@ -275,12 +275,12 @@ The return code indicates success or failure. ## update -Corresponding HTTP API Endpoint: [\[PUT\] /v1/operator/area/:uuid](/api-docs/operator/area#update-network-area) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/operator/area/:uuid](/consul/api-docs/operator/area#update-network-area) This command updates the configuration of network area. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/operator/autopilot.mdx b/website/content/commands/operator/autopilot.mdx index 492a15eb14..1b4f43409c 100644 --- a/website/content/commands/operator/autopilot.mdx +++ b/website/content/commands/operator/autopilot.mdx @@ -12,7 +12,7 @@ Command: `consul operator autopilot` The Autopilot operator command is used to interact with Consul's Autopilot subsystem. The command can be used to view or modify the current Autopilot configuration. See the -[Autopilot Guide](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations) for more information about Autopilot. +[Autopilot Guide](/consul/tutorials/datacenter-operations/autopilot-datacenter-operations) for more information about Autopilot. ```text Usage: consul operator autopilot [options] @@ -28,12 +28,12 @@ Subcommands: ## get-config -Corresponding HTTP API Endpoint: [\[GET\] /v1/operator/autopilot/configuration](/api-docs/operator/autopilot#read-configuration) +Corresponding HTTP API Endpoint: [\[GET\] /v1/operator/autopilot/configuration](/consul/api-docs/operator/autopilot#read-configuration) This command displays the current autopilot configuration. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -63,12 +63,12 @@ UpgradeMigrationTag = "" ## set-config -Corresponding HTTP API Endpoint: [\[PUT\] /v1/operator/autopilot/configuration](/api-docs/operator/autopilot#update-configuration) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/operator/autopilot/configuration](/consul/api-docs/operator/autopilot#update-configuration) Modifies the current Autopilot configuration. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -107,10 +107,10 @@ The return code indicates success or failure. - `-disable-upgrade-migration` - Controls whether Consul will avoid promoting new servers until it can perform a migration. Must be one of `[true|false]`. -- `-redundancy-zone-tag` - Controls the [`-node-meta`](/docs/agent/config/cli-flags#_node_meta) +- `-redundancy-zone-tag` - Controls the [`-node-meta`](/consul/docs/agent/config/cli-flags#_node_meta) key name used for separating servers into different redundancy zones. -- `-upgrade-version-tag` - Controls the [`-node-meta`](/docs/agent/config/cli-flags#_node_meta) +- `-upgrade-version-tag` - Controls the [`-node-meta`](/consul/docs/agent/config/cli-flags#_node_meta) tag to use for version info when performing upgrade migrations. If left blank, the Consul version will be used. #### API Options @@ -121,12 +121,12 @@ The return code indicates success or failure. ## state -Corresponding HTTP API Endpoint: [\[GET\] /v1/operator/autopilot/state](/api-docs/operator/autopilot#read-the-autopilot-state) +Corresponding HTTP API Endpoint: [\[GET\] /v1/operator/autopilot/state](/consul/api-docs/operator/autopilot#read-the-autopilot-state) This command displays the current autopilot state. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/operator/index.mdx b/website/content/commands/operator/index.mdx index af34e18143..14ba329052 100644 --- a/website/content/commands/operator/index.mdx +++ b/website/content/commands/operator/index.mdx @@ -18,11 +18,11 @@ outage and even loss of data. If ACLs are enabled then a token with operator privileges may be required in order to use this command. Requests are forwarded internally to the leader if required, so this can be run from any Consul node in a cluster. See the -[ACL Guide](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) for more information. +[ACL Guide](/consul/tutorials/security/access-control-setup-production) for more information. -See the [Outage Recovery](https://learn.hashicorp.com/tutorials/consul/recovery-outage) guide for some examples of how +See the [Outage Recovery](/consul/tutorials/datacenter-operations/recovery-outage) guide for some examples of how this command is used. For an API to perform these operations programmatically, -please see the documentation for the [Operator](/api-docs/operator) +please see the documentation for the [Operator](/consul/api-docs/operator) endpoint. ## Usage @@ -42,6 +42,6 @@ Subcommands: For more information, examples, and usage about a subcommand, click on the name of the subcommand in the sidebar or one of the links below: -- [area](/commands/operator/area) -- [autopilot](/commands/operator/autopilot) -- [raft](/commands/operator/raft) +- [area](/consul/commands/operator/area) +- [autopilot](/consul/commands/operator/autopilot) +- [raft](/consul/commands/operator/raft) diff --git a/website/content/commands/operator/raft.mdx b/website/content/commands/operator/raft.mdx index aa9d9ffc93..857a9ee1ac 100644 --- a/website/content/commands/operator/raft.mdx +++ b/website/content/commands/operator/raft.mdx @@ -29,12 +29,12 @@ Subcommands: ## list-peers -Corresponding HTTP API Endpoint: [\[GET\] /v1/status/peers](/api-docs/status#list-raft-peers) +Corresponding HTTP API Endpoint: [\[GET\] /v1/status/peers](/consul/api-docs/status#list-raft-peers) This command displays the current Raft peer configuration. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -75,7 +75,7 @@ configuration. ## remove-peer -Corresponding HTTP API Endpoint: [\[DELETE\] /v1/operator/raft/peer](/api-docs/operator/raft#delete-raft-peer) +Corresponding HTTP API Endpoint: [\[DELETE\] /v1/operator/raft/peer](/consul/api-docs/operator/raft#delete-raft-peer) This command removes the Consul server with given address from the Raft configuration. @@ -83,13 +83,13 @@ There are rare cases where a peer may be left behind in the Raft configuration even though the server is no longer present and known to the cluster. This command can be used to remove the failed server so that it is no longer affects the Raft quorum. If the server still shows in the output of the -[`consul members`](/commands/members) command, it is preferable to +[`consul members`](/consul/commands/members) command, it is preferable to clean up by simply running -[`consul force-leave`](/commands/force-leave) +[`consul force-leave`](/consul/commands/force-leave) instead of this command. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -107,14 +107,14 @@ The return code will indicate success or failure. ## transfer-leader -Corresponding HTTP API Endpoint: [\[POST\] /v1/operator/raft/transfer-leader](/api-docs/operator/raft#transfer-raft-leadership) +Corresponding HTTP API Endpoint: [\[POST\] /v1/operator/raft/transfer-leader](/consul/api-docs/operator/raft#transfer-raft-leadership) This command transfers Raft leadership to another server agent. If an `id` is provided, Consul transfers leadership to the server with that id. Use this command to change leadership without restarting the leader node, which maintains quorum and workload capacity. -The table below shows this command's [required ACLs](/api-docs#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/partition.mdx b/website/content/commands/partition.mdx index 5b9fed9a39..660ea71cca 100644 --- a/website/content/commands/partition.mdx +++ b/website/content/commands/partition.mdx @@ -73,7 +73,7 @@ This subcommand has the following characteristics: | Characteristic | Value | | -------------- | ----- | | [Required ACLs] | `operator:write` | -| Corresponding HTTP API endpoint | [\[PUT\] /v1/partition](/api-docs/admin-partitions#create-a-partition) | +| Corresponding HTTP API endpoint | [\[PUT\] /v1/partition](/consul/api-docs/admin-partitions#create-a-partition) | The admin partition is created according to the values specified in the options. You can specify the following options: @@ -105,7 +105,7 @@ This subcommand has the following characteristics: | Characteristic | Value | | -------------- | ----- | | [Required ACLs] | `operator:write` | -| Corresponding HTTP API endpoint | [\[PUT\] /v1/partition/:name](/api-docs/admin-partitions#update-a-partition) | +| Corresponding HTTP API endpoint | [\[PUT\] /v1/partition/:name](/consul/api-docs/admin-partitions#update-a-partition) | Use the following syntax to write from file: @@ -149,7 +149,7 @@ This subcommand has the following characteristics: | Characteristic | Value | | -------------- | ----- | | [Required ACLs] | `operator:read`; however, a non-anonymous token can always read its own partition | -| Corresponding HTTP API endpoint | [\[GET\] /v1/partition/:name](/api-docs/admin-partitions#read-a-partition) | +| Corresponding HTTP API endpoint | [\[GET\] /v1/partition/:name](/consul/api-docs/admin-partitions#read-a-partition) | The admin partition is created according to the values specified in the options. You can specify the following options: @@ -178,7 +178,7 @@ This subcommand has the following characteristics: | Characteristic | Value | | -------------- | ----- | | [Required ACLs] | `operator:read` | -| Corresponding HTTP API endpoint | [\[GET\] /v1/partitions](/api-docs/admin-partitions#list-all-partitions) | +| Corresponding HTTP API endpoint | [\[GET\] /v1/partitions](/consul/api-docs/admin-partitions#list-all-partitions) | The admin partition is created according to the values specified in the options. You can specify the following options: @@ -221,7 +221,7 @@ This subcommand has the following characteristics: | Characteristic | Value | | -------------- | ----- | | [Required ACLs] | `operator:write` | -| Corresponding HTTP API endpoint | [\[DELETE\] /v1/partitions](/api-docs/admin-partitions#delete-a-partition) | +| Corresponding HTTP API endpoint | [\[DELETE\] /v1/partitions](/consul/api-docs/admin-partitions#delete-a-partition) | In the following example, the `webdev-bu` partition is deleted: diff --git a/website/content/commands/peering/delete.mdx b/website/content/commands/peering/delete.mdx index 2c6d31d8f4..b18bb4a59d 100644 --- a/website/content/commands/peering/delete.mdx +++ b/website/content/commands/peering/delete.mdx @@ -8,7 +8,7 @@ description: Learn how to use the consul peering delete command to remove a peer Command: `consul peering delete` -Corresponding HTTP API Endpoint: [\[DELETE\] /v1/peering/:name](/api-docs/peering#delete-a-peering-connection) +Corresponding HTTP API Endpoint: [\[DELETE\] /v1/peering/:name](/consul/api-docs/peering#delete-a-peering-connection) The `peering delete` removes a peering connection with another cluster. Consul deletes all data imported from the peer in the background. @@ -17,7 +17,7 @@ Operators can still read the peering connections while the data is being removed The command adds a `DeletedAt` field to the peering connection object with the timestamp of when the peering was marked for deletion. You can only use a peering token to establish the connection once. If you need to reestablish a peering connection, you must generate a new token. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). | ACL Required | | ------------ | diff --git a/website/content/commands/peering/establish.mdx b/website/content/commands/peering/establish.mdx index a8cea75c7d..31a2d01f38 100644 --- a/website/content/commands/peering/establish.mdx +++ b/website/content/commands/peering/establish.mdx @@ -8,14 +8,14 @@ description: Learn how to use the consul peering establish command to establish Command: `consul peering establish` -Corresponding HTTP API Endpoint: [\[POST\] /v1/peering/establish](/api-docs/peering#establish-a-peering-connection) +Corresponding HTTP API Endpoint: [\[POST\] /v1/peering/establish](/consul/api-docs/peering#establish-a-peering-connection) The `peering establish` starts a peering connection with the cluster that generated the peering token. -You can generate cluster peering tokens using the [`consul peering generate-token`](/commands/peering/generate-token) command or the [HTTP API](/api-docs/peering#generate-a-peering-token). +You can generate cluster peering tokens using the [`consul peering generate-token`](/consul/commands/peering/generate-token) command or the [HTTP API](/consul/api-docs/peering#generate-a-peering-token). You can only use a peering token to establish the connection once. If you need to reestablish a peering connection, you must generate a new token. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). | ACL Required | | ------------ | diff --git a/website/content/commands/peering/generate-token.mdx b/website/content/commands/peering/generate-token.mdx index 60aec62f1c..ecfe22bd6e 100644 --- a/website/content/commands/peering/generate-token.mdx +++ b/website/content/commands/peering/generate-token.mdx @@ -8,14 +8,14 @@ description: Learn how to use the consul peering generate-token command to gener Command: `consul peering generate-token` -Corresponding HTTP API Endpoint: [\[POST\] /v1/peering/token](/api-docs/peering#generate-a-peering-token) +Corresponding HTTP API Endpoint: [\[POST\] /v1/peering/token](/consul/api-docs/peering#generate-a-peering-token) The `peering generate-token` generates a peering token. The token is base 64-encoded string containing the token details. -This token should be transferred to the other cluster being peered and consumed using [`consul peering establish`](/commands/peering/establish). +This token should be transferred to the other cluster being peered and consumed using [`consul peering establish`](/consul/commands/peering/establish). Generating a token and specifying the same local name associated with a previously-generated token does not affect active connections established with the original token. If the previously-generated token is not actively being used for a peer connection, however, it will become invalid when the new token with the same local name is generated. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). | ACL Required | | ------------ | diff --git a/website/content/commands/peering/index.mdx b/website/content/commands/peering/index.mdx index 47311a444a..c4669fc3ac 100644 --- a/website/content/commands/peering/index.mdx +++ b/website/content/commands/peering/index.mdx @@ -8,7 +8,7 @@ page_title: 'Commands: Peering' Command: `consul peering` Use the `peering` command to create and manage peering connections between Consul clusters, including token generation and consumption. Refer to -[Create and Manage Peerings Connections](/docs/connect/cluster-peering/create-manage-peering) for an +[Create and Manage Peerings Connections](/consul/docs/connect/cluster-peering/create-manage-peering) for an overview of the CLI workflow for cluster peering. ## Usage @@ -30,11 +30,11 @@ Subcommands: For more information, examples, and usage about a subcommand, click on the name of the subcommand in the sidebar or one of the links below: -- [delete](/commands/peering/delete) -- [establish](/commands/peering/establish) -- [generate-token](/commands/peering/generate-token) -- [list](/commands/peering/list) -- [read](/commands/peering/read) +- [delete](/consul/commands/peering/delete) +- [establish](/consul/commands/peering/establish) +- [generate-token](/consul/commands/peering/generate-token) +- [list](/consul/commands/peering/list) +- [read](/consul/commands/peering/read) diff --git a/website/content/commands/peering/list.mdx b/website/content/commands/peering/list.mdx index 6b23ceaaa7..e66b97e14d 100644 --- a/website/content/commands/peering/list.mdx +++ b/website/content/commands/peering/list.mdx @@ -7,12 +7,12 @@ page_title: 'Commands: Peering List' Command: `consul peering List` -Corresponding HTTP API Endpoint: [\[GET\] /v1/peerings](/api-docs/peering#list-all-peerings) +Corresponding HTTP API Endpoint: [\[GET\] /v1/peerings](/consul/api-docs/peering#list-all-peerings) The `peering list` lists all peering connections. The results are filtered according to ACL policy configuration. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). | ACL Required | | ------------ | diff --git a/website/content/commands/peering/read.mdx b/website/content/commands/peering/read.mdx index c1b178829c..58908656a6 100644 --- a/website/content/commands/peering/read.mdx +++ b/website/content/commands/peering/read.mdx @@ -7,11 +7,11 @@ page_title: 'Commands: Peering Read' Command: `consul peering read` -Corresponding HTTP API Endpoint: [\[GET\] /v1/peering/:name](/api-docs/peering#read-a-peering-connection) +Corresponding HTTP API Endpoint: [\[GET\] /v1/peering/:name](/consul/api-docs/peering#read-a-peering-connection) The `peering read` displays information on the status of a peering connection. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). | ACL Required | | ------------ | diff --git a/website/content/commands/reload.mdx b/website/content/commands/reload.mdx index e070230c36..a7eaa45df3 100644 --- a/website/content/commands/reload.mdx +++ b/website/content/commands/reload.mdx @@ -8,7 +8,7 @@ description: The `reload` command triggers a reload of configuration files for t Command: `consul reload` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/reload](/api-docs/agent#reload-agent) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/reload](/consul/api-docs/agent#reload-agent) The `reload` command triggers a reload of configuration files for the agent. @@ -22,11 +22,11 @@ reload will be present in the agent logs and not in the output of this command. **NOTE** Not all configuration options are reloadable. See the -[Reloadable Configuration](/docs/agent/config#reloadable-configuration) +[Reloadable Configuration](/consul/docs/agent/config#reloadable-configuration) section on the agent options page for details on which options are supported. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/rtt.mdx b/website/content/commands/rtt.mdx index 15f31a22cc..0fc2bd37ab 100644 --- a/website/content/commands/rtt.mdx +++ b/website/content/commands/rtt.mdx @@ -9,16 +9,16 @@ description: | Command: `consul rtt` -Corresponding HTTP API Endpoints: [\[GET\] /v1/coordinate/datacenters](/api-docs/coordinate#read-wan-coordinates), [\[GET\] /v1/coordinate/nodes](/api-docs/coordinate#read-lan-coordinates-for-all-nodes) +Corresponding HTTP API Endpoints: [\[GET\] /v1/coordinate/datacenters](/consul/api-docs/coordinate#read-wan-coordinates), [\[GET\] /v1/coordinate/nodes](/consul/api-docs/coordinate#read-lan-coordinates-for-all-nodes) The `rtt` command estimates the network round trip time between two nodes using Consul's network coordinate model of the cluster. -See the [Network Coordinates](/docs/architecture/coordinates) internals guide +See the [Network Coordinates](/consul/docs/architecture/coordinates) internals guide for more information on how these coordinates are computed. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/services/deregister.mdx b/website/content/commands/services/deregister.mdx index c143620955..4b65eea651 100644 --- a/website/content/commands/services/deregister.mdx +++ b/website/content/commands/services/deregister.mdx @@ -7,7 +7,7 @@ page_title: 'Commands: Services Deregister' Command: `consul services deregister` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/service/deregister/:service_id](/api-docs/agent/service#deregister-service) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/service/deregister/:service_id](/consul/api-docs/agent/service#deregister-service) The `services deregister` command deregisters a service with the local agent. Note that this command can only deregister services that were registered @@ -16,12 +16,12 @@ be paired with `services register`. This is just one method for service deregistration. If the service was registered with a configuration file, then deleting that file and -[reloading](/commands/reload) Consul is the correct method to -deregister. See [Service Definition](/docs/discovery/services) for more +[reloading](/consul/commands/reload) Consul is the correct method to +deregister. See [Service Definition](/consul/docs/discovery/services) for more information about registering services generally. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | diff --git a/website/content/commands/services/index.mdx b/website/content/commands/services/index.mdx index 95c3f868e4..7b5b8f3f68 100644 --- a/website/content/commands/services/index.mdx +++ b/website/content/commands/services/index.mdx @@ -8,11 +8,11 @@ page_title: 'Commands: Services' Command: `consul services` The `services` command has subcommands for interacting with Consul services -registered with the [local agent](/docs/agent). These provide +registered with the [local agent](/consul/docs/agent). These provide useful commands such as `register` and `deregister` for easily registering services in scripts, dev mode, etc. To view all services in the catalog, instead of only agent-local services, -see the [`catalog services`](/commands/catalog/services) command. +see the [`catalog services`](/consul/commands/catalog/services) command. ## Usage diff --git a/website/content/commands/services/register.mdx b/website/content/commands/services/register.mdx index 68d3f6deab..d7266d26fe 100644 --- a/website/content/commands/services/register.mdx +++ b/website/content/commands/services/register.mdx @@ -7,7 +7,7 @@ page_title: 'Commands: Services Register' Command: `consul services register` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/service/register](/api-docs/agent/service#register-service) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/agent/service/register](/consul/api-docs/agent/service#register-service) The `services register` command registers a service with the local agent. This command returns after registration and must be paired with explicit @@ -15,15 +15,15 @@ service deregistration. This command simplifies service registration from scripts, in dev mode, etc. This is just one method of service registration. Services can also be -registered by placing a [service definition](/docs/discovery/services) +registered by placing a [service definition](/consul/docs/discovery/services) in the Consul agent configuration directory and issuing a -[reload](/commands/reload). This approach is easiest for +[reload](/consul/commands/reload). This approach is easiest for configuration management systems that other systems that have access to the configuration directory. Clients may also use the -[HTTP API](/api-docs/agent/service) directly. +[HTTP API](/consul/api-docs/agent/service) directly. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -44,7 +44,7 @@ This command returns after registration succeeds. It must be paired with a deregistration command or API call to remove the service. To ensure that services are properly deregistered, it is **highly recommended** that a check is created with the -[`DeregisterCriticalServiceAfter`](/api-docs/agent/check#deregistercriticalserviceafter) +[`DeregisterCriticalServiceAfter`](/consul/api-docs/agent/check#deregistercriticalserviceafter) configuration set. This will ensure that even if deregistration failed for any reason, the agent will automatically deregister the service instance after it is unhealthy for the specified period of time. @@ -64,7 +64,7 @@ arguments are given, the flags below can be used to register a single service. Note that the behavior of each of the fields below is exactly the same -as when constructing a standard [service definition](/docs/discovery/services). +as when constructing a standard [service definition](/consul/docs/discovery/services). Please refer to that documentation for full details. - `-id` - The ID of the service. This will default to `-name` if not set. diff --git a/website/content/commands/snapshot/agent.mdx b/website/content/commands/snapshot/agent.mdx index 4ff46dee38..0eee4228dd 100644 --- a/website/content/commands/snapshot/agent.mdx +++ b/website/content/commands/snapshot/agent.mdx @@ -9,9 +9,9 @@ Command: `consul snapshot agent` -~> The [`agent`](/commands/snapshot/agent) subcommand described here is +~> The [`agent`](/consul/commands/snapshot/agent) subcommand described here is available only in [Consul Enterprise](https://www.hashicorp.com/products/consul/) -version 0.7.1 and later. All other [snapshot subcommands](/commands/snapshot) +version 0.7.1 and later. All other [snapshot subcommands](/consul/commands/snapshot) are available in the open source version of Consul. The `snapshot agent` subcommand starts a process that takes snapshots of the @@ -48,8 +48,8 @@ in the file name when using local storage, or in the object key when using remote storage. Snapshots can be restored using the -[`consul snapshot restore`](/commands/snapshot/restore) command, or -the [HTTP API](/api-docs/snapshot). +[`consul snapshot restore`](/consul/commands/snapshot/restore) command, or +the [HTTP API](/consul/api-docs/snapshot). ## ACL permissions @@ -413,7 +413,7 @@ leader election or service registration: $ consul snapshot agent -interval=0 ``` -Please see the [HTTP API](/api-docs/snapshot) documentation for +Please see the [HTTP API](/consul/api-docs/snapshot) documentation for more details about snapshot internals. ## Licensing @@ -431,5 +431,5 @@ then the order of precedence is as follows: 3. `license_path` configuration. The ability to load licenses from the configuration or environment was added in v1.10.0, -v1.9.7 and v1.8.13. See the [licensing documentation](/docs/enterprise/license/overview) for +v1.9.7 and v1.8.13. See the [licensing documentation](/consul/docs/enterprise/license/overview) for more information about Consul Enterprise license management. diff --git a/website/content/commands/snapshot/index.mdx b/website/content/commands/snapshot/index.mdx index 8c872642a0..c21e9d32e6 100644 --- a/website/content/commands/snapshot/index.mdx +++ b/website/content/commands/snapshot/index.mdx @@ -12,7 +12,7 @@ state of the Consul servers for disaster recovery. These are atomic, point-in-ti snapshots which include key/value entries, service catalog, prepared queries, sessions, and ACLs. This command is available in Consul 0.7.1 and later. -Snapshots are also accessible via the [HTTP API](/api-docs/snapshot). +Snapshots are also accessible via the [HTTP API](/consul/api-docs/snapshot). ## Usage @@ -37,10 +37,10 @@ Subcommands: For more information, examples, and usage about a subcommand, click on the name of the subcommand in the sidebar or one of the links below: -- [agent](/commands/snapshot/agent) -- [inspect](/commands/snapshot/inspect) -- [restore](/commands/snapshot/restore) -- [save](/commands/snapshot/save) +- [agent](/consul/commands/snapshot/agent) +- [inspect](/consul/commands/snapshot/inspect) +- [restore](/consul/commands/snapshot/restore) +- [save](/consul/commands/snapshot/save) ## Basic Examples diff --git a/website/content/commands/snapshot/inspect.mdx b/website/content/commands/snapshot/inspect.mdx index ef5c03cc02..596d8a5969 100644 --- a/website/content/commands/snapshot/inspect.mdx +++ b/website/content/commands/snapshot/inspect.mdx @@ -13,8 +13,8 @@ service catalog, prepared queries, sessions, and ACLs. The snapshot is read from the given file. -> Typically this is used with Consul self-contained Snapshot files obtained -using the [`consul snapshot`](/commands/snapshot) command or [Snapshot -API](/api-docs/snapshot#generate-snapshot). If the file provided is named +using the [`consul snapshot`](/consul/commands/snapshot) command or [Snapshot +API](/consul/api-docs/snapshot#generate-snapshot). If the file provided is named `state.bin` however, the command will assume it is a raw raft snapshot in a Consul server data directory and will attempt to read it directly. The `state.bin` file must still be in the same directory as it's associated @@ -129,7 +129,7 @@ $ consul snapshot inspect -kvdetails -kvdepth 3 -kvfilter vault/core backup.snap Total 5.9KB ``` -Please see the [HTTP API](/api-docs/snapshot) documentation for +Please see the [HTTP API](/consul/api-docs/snapshot) documentation for more details about snapshot internals. To inspect an internal snapshot directly from a Consul server data directory: diff --git a/website/content/commands/snapshot/restore.mdx b/website/content/commands/snapshot/restore.mdx index d80d3ab059..0e3194e72e 100644 --- a/website/content/commands/snapshot/restore.mdx +++ b/website/content/commands/snapshot/restore.mdx @@ -7,7 +7,7 @@ page_title: 'Commands: Snapshot Restore' Command: `consul snapshot restore` -Corresponding HTTP API Endpoint: [\[PUT\] /v1/snapshot](/api-docs/snapshot#restore-snapshot) +Corresponding HTTP API Endpoint: [\[PUT\] /v1/snapshot](/consul/api-docs/snapshot#restore-snapshot) The `snapshot restore` command is used to restore an atomic, point-in-time snapshot of the state of the Consul servers which includes key/value entries, @@ -20,8 +20,8 @@ intended to recover from a disaster. It restores your configuration into a fresh cluster of Consul servers as long as your new cluster runs the same Consul version as the cluster that originally took the snapshot. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -47,5 +47,5 @@ $ consul snapshot restore backup.snap Restored snapshot ``` -Please see the [HTTP API](/api-docs/snapshot) documentation for +Please see the [HTTP API](/consul/api-docs/snapshot) documentation for more details about snapshot internals. diff --git a/website/content/commands/snapshot/save.mdx b/website/content/commands/snapshot/save.mdx index 6ecf822937..397e82f6ff 100644 --- a/website/content/commands/snapshot/save.mdx +++ b/website/content/commands/snapshot/save.mdx @@ -7,7 +7,7 @@ page_title: 'Commands: Snapshot Save' Command: `consul snapshot save` -Corresponding HTTP API Endpoint: [\[GET\] /v1/snapshot](/api-docs/snapshot#generate-snapshot) +Corresponding HTTP API Endpoint: [\[GET\] /v1/snapshot](/consul/api-docs/snapshot#generate-snapshot) The `snapshot save` command is used to retrieve an atomic, point-in-time snapshot of the state of the Consul servers which includes key/value entries, @@ -27,8 +27,8 @@ the CLI client attempting to perform a snapshot save will have no effect. It _mu the context of the server process. If you're using Systemd to manage your Consul server processes, then adding `Environment=TMPDIR=/path/to/dir` to your Consul unit file will work. -The table below shows this command's [required ACLs](/api-docs/api-structure#authentication). Configuration of -[blocking queries](/api-docs/features/blocking) and [agent caching](/api-docs/features/caching) +The table below shows this command's [required ACLs](/consul/api-docs/api-structure#authentication). Configuration of +[blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching) are not supported from commands, but may be from the corresponding HTTP endpoint. | ACL Required | @@ -73,5 +73,5 @@ This is useful for situations where a cluster is in a degraded state and no leader is available. To target a specific server for a snapshot, you can run the `consul snapshot save` command on that specific server. -Please see the [HTTP API](/api-docs/snapshot) documentation for +Please see the [HTTP API](/consul/api-docs/snapshot) documentation for more details about snapshot internals. diff --git a/website/content/commands/validate.mdx b/website/content/commands/validate.mdx index abdb0657f4..a435f29120 100644 --- a/website/content/commands/validate.mdx +++ b/website/content/commands/validate.mdx @@ -21,7 +21,7 @@ to be loaded by the agent. This command cannot operate on partial configuration fragments since those won't pass the full agent validation. For more information on the format of Consul's configuration files, read the -consul agent [Configuration Files](/docs/agent/config/config-files) +consul agent [Configuration Files](/consul/docs/agent/config/config-files) section. ## Usage diff --git a/website/content/commands/watch.mdx b/website/content/commands/watch.mdx index 4518a257dc..da32cdefdc 100644 --- a/website/content/commands/watch.mdx +++ b/website/content/commands/watch.mdx @@ -19,7 +19,7 @@ a process with the latest values of the view. If no process is specified, the current values are dumped to STDOUT which can be a useful way to inspect data in Consul. -There is more [documentation on watches here](/docs/dynamic-app-config/watches). +There is more [documentation on watches here](/consul/docs/dynamic-app-config/watches). ## Usage @@ -28,7 +28,7 @@ Usage: `consul watch [options] [child...]` The only required option is `-type` which specifies the particular data view. Depending on the type, various options may be required or optionally provided. There is more documentation on watch -[specifications here](/docs/dynamic-app-config/watches). +[specifications here](/consul/docs/dynamic-app-config/watches). #### Command Options diff --git a/website/content/docs/agent/config-entries.mdx b/website/content/docs/agent/config-entries.mdx index cf76990359..f4b7f97f14 100644 --- a/website/content/docs/agent/config-entries.mdx +++ b/website/content/docs/agent/config-entries.mdx @@ -44,26 +44,26 @@ metadata: ## Supported Config Entries -See [Service Mesh - Config Entries](/docs/connect/config-entries) for the list +See [Service Mesh - Config Entries](/consul/docs/connect/config-entries) for the list of supported config entries. ## Managing Configuration Entries In Kubernetes -See [Kubernetes Custom Resource Definitions](/docs/k8s/crds). +See [Kubernetes Custom Resource Definitions](/consul/docs/k8s/crds). ## Managing Configuration Entries Outside Of Kubernetes Configuration entries outside of Kubernetes should be managed with the Consul -[CLI](/commands/config) or [API](/api-docs/config). Additionally, as a +[CLI](/consul/commands/config) or [API](/consul/api-docs/config). Additionally, as a convenience for initial cluster bootstrapping, configuration entries can be specified in all of the Consul servers's -[configuration files](/docs/agent/config/config-files#config_entries_bootstrap) +[configuration files](/consul/docs/agent/config/config-files#config_entries_bootstrap) ### Managing Configuration Entries with the CLI #### Creating or Updating a Configuration Entry -The [`consul config write`](/commands/config/write) command is used to +The [`consul config write`](/consul/commands/config/write) command is used to create and update configuration entries. This command will load either a JSON or HCL file holding the configuration entry definition and then will push this configuration to Consul. @@ -97,7 +97,7 @@ overwriting other unknown modifications. #### Reading a Configuration Entry -The [`consul config read`](/commands/config/read) command is used to +The [`consul config read`](/consul/commands/config/read) command is used to read the current value of a configuration entry. The configuration entry will be displayed in JSON form which is how its transmitted between the CLI client and Consul's HTTP API. @@ -115,7 +115,7 @@ $ consul config read -kind service-defaults -name web #### Listing Configuration Entries -The [`consul config list`](/commands/config/list) command is used to +The [`consul config list`](/consul/commands/config/list) command is used to list out all the configuration entries for a given kind. Example: @@ -129,7 +129,7 @@ db #### Deleting Configuration Entries -The [`consul config delete`](/commands/config/delete) command is used +The [`consul config delete`](/consul/commands/config/delete) command is used to delete an entry by specifying both its `kind` and `name`. Example: @@ -161,7 +161,7 @@ api ### Bootstrapping From A Configuration File Configuration entries can be bootstrapped by adding them [inline to each Consul -server's configuration file](/docs/agent/config/config-files#config_entries). When a +server's configuration file](/consul/docs/agent/config/config-files#config_entries). When a server gains leadership, it will attempt to initialize the configuration entries. If a configuration entry does not already exist outside of the servers configuration, then it will create it. If a configuration entry does exist, that diff --git a/website/content/docs/agent/config/cli-flags.mdx b/website/content/docs/agent/config/cli-flags.mdx index c965a8921f..ebcdb4c076 100644 --- a/website/content/docs/agent/config/cli-flags.mdx +++ b/website/content/docs/agent/config/cli-flags.mdx @@ -7,13 +7,13 @@ description: >- # Agents Command-line Reference ((#commandline_options)) --> **Note:** Some CLI arguments may be different from HCL keys. See [Configuration Key Reference](/docs/agent/config/config-files#config_key_reference) for equivalent HCL Keys. +-> **Note:** Some CLI arguments may be different from HCL keys. See [Configuration Key Reference](/consul/docs/agent/config/config-files#config_key_reference) for equivalent HCL Keys. This topic describes the available command-line options for the Consul agent. ## Usage -See [Agent Overview](/docs/agent#starting-the-consul-agent) for examples of how to use flags with the `consul agent` CLI. +See [Agent Overview](/consul/docs/agent#starting-the-consul-agent) for examples of how to use flags with the `consul agent` CLI. ## Environment Variables @@ -21,19 +21,19 @@ Environment variables **cannot** be used to configure the Consul client. They _can_ be used when running other `consul` CLI commands that connect with a running agent, e.g. `CONSUL_HTTP_ADDR=192.168.0.1:8500 consul members`. -See [Consul Commands](/commands#environment-variables) for more +See [Consul Commands](/consul/commands#environment-variables) for more information. ## General -- `-auto-reload-config` ((#\_auto_reload_config)) - This option directs Consul to automatically reload the [reloadable configuration options](/docs/agent/config#reloadable-configuration) when configuration files change. +- `-auto-reload-config` ((#\_auto_reload_config)) - This option directs Consul to automatically reload the [reloadable configuration options](/consul/docs/agent/config#reloadable-configuration) when configuration files change. Consul also watches the certificate and key files specified with the `cert_file` and `key_file` parameters and reloads the configuration if the files are updated. - `-check_output_max_size` - Override the default limit of 4k for maximum size of checks, this is a positive value. By limiting this size, it allows to put less pressure on Consul servers when many checks are having a very large output in their checks. In order to completely disable check output - capture, it is possible to use [`discard_check_output`](/docs/agent/config/config-files#discard_check_output). + capture, it is possible to use [`discard_check_output`](/consul/docs/agent/config/config-files#discard_check_output). - `-client` ((#\_client)) - The address to which Consul will bind client interfaces, including the HTTP and DNS servers. By default, this is "127.0.0.1", @@ -82,7 +82,7 @@ information. - `-dev` ((#\_dev)) - Enable development server mode. This is useful for quickly starting a Consul agent with all persistence options turned off, enabling an in-memory server which can be used for rapid prototyping or developing against - the API. In this mode, [Connect is enabled](/docs/connect/configuration) and + the API. In this mode, [Connect is enabled](/consul/docs/connect/configuration) and will by default create a new root CA certificate on startup. This mode is **not** intended for production use as it does not write any data to disk. The gRPC port is also defaulted to `8502` in this mode. @@ -92,7 +92,7 @@ information. only the given `-encrypt` key will be available on startup. This defaults to false. - `-enable-script-checks` ((#\_enable_script_checks)) This controls whether - [health checks that execute scripts](/docs/discovery/checks) are enabled on this + [health checks that execute scripts](/consul/docs/discovery/checks) are enabled on this agent, and defaults to `false` so operators must opt-in to allowing these. This was added in Consul 0.9.0. @@ -109,7 +109,7 @@ information. - `-encrypt` ((#\_encrypt)) - Specifies the secret key to use for encryption of Consul network traffic. This key must be 32-bytes that are Base64-encoded. The - easiest way to create an encryption key is to use [`consul keygen`](/commands/keygen). + easiest way to create an encryption key is to use [`consul keygen`](/consul/commands/keygen). All nodes within a cluster must share the same encryption key to communicate. The provided key is automatically persisted to the data directory and loaded automatically whenever the agent is restarted. This means that to encrypt Consul's gossip protocol, @@ -118,7 +118,7 @@ information. the provided key is ignored and a warning will be displayed. - `-grpc-port` ((#\_grpc_port)) - the gRPC API port to listen on. Default - -1 (gRPC disabled). See [ports](/docs/agent/config#ports-used) documentation for more detail. + -1 (gRPC disabled). See [ports](/consul/docs/agent/config#ports-used) documentation for more detail. - `-hcl` ((#\_hcl)) - A HCL configuration fragment. This HCL configuration fragment is appended to the configuration and allows to specify the full range @@ -131,7 +131,7 @@ information. allowing you to set the port directly via a Procfile. - `-https-port` ((#\_https_port)) - the HTTPS API port to listen on. Default - -1 (https disabled). See [ports](/docs/agent/config#ports-used) documentation for more detail. + -1 (https disabled). See [ports](/consul/docs/agent/config#ports-used) documentation for more detail. - `-default-query-time` ((#\_default_query_time)) - This flag controls the amount of time a blocking query will wait before Consul will force a response. @@ -148,21 +148,21 @@ information. to close the agent or `SIGHUP` to update check definitions) to the agent. - `-protocol` ((#\_protocol)) - The Consul protocol version to use. Consul - agents speak protocol 2 by default, however agents will automatically use protocol > 2 when speaking to compatible agents. This should be set only when [upgrading](/docs/upgrading). You can view the protocol versions supported by Consul by running `consul version`. + agents speak protocol 2 by default, however agents will automatically use protocol > 2 when speaking to compatible agents. This should be set only when [upgrading](/consul/docs/upgrading). You can view the protocol versions supported by Consul by running `consul version`. - `-raft-protocol` ((#\_raft_protocol)) - This controls the internal version of the Raft consensus protocol used for server communications. This must be set - to 3 in order to gain access to Autopilot features, with the exception of [`cleanup_dead_servers`](/docs/agent/config/config-files#cleanup_dead_servers). Defaults to 3 in Consul 1.0.0 and later (defaulted to 2 previously). See [Raft Protocol Version Compatibility](/docs/upgrading/upgrade-specific#raft-protocol-version-compatibility) for more details. + to 3 in order to gain access to Autopilot features, with the exception of [`cleanup_dead_servers`](/consul/docs/agent/config/config-files#cleanup_dead_servers). Defaults to 3 in Consul 1.0.0 and later (defaulted to 2 previously). See [Raft Protocol Version Compatibility](/consul/docs/upgrading/upgrade-specific#raft-protocol-version-compatibility) for more details. - `-segment` ((#\_segment)) - This flag is used to set the name of the network segment the agent belongs to. An agent can only join and communicate with other agents within its network segment. Ensure the [join - operation uses the correct port for this segment](/docs/enterprise/network-segments#join_a_client_to_a_segment). + operation uses the correct port for this segment](/consul/docs/enterprise/network-segments#join_a_client_to_a_segment). Review the [Network Segments documentation](/consul/docs/enterprise/network-segments/create-network-segment) for more details. By default, this is an empty string, which is the `` network segment. - ~> **Warning:** The `segment` flag cannot be used with the [`partition`](/docs/agent/config/config-files#partition-1) option. + ~> **Warning:** The `segment` flag cannot be used with the [`partition`](/consul/docs/agent/config/config-files#partition-1) option. ## Advertise Address Options @@ -184,13 +184,13 @@ information. - `-advertise-wan` ((#\_advertise-wan)) - The advertise WAN address is used to change the address that we advertise to server nodes joining through the WAN. - This can also be set on client agents when used in combination with the [`translate_wan_addrs`](/docs/agent/config/config-files#translate_wan_addrs) configuration option. By default, the [`-advertise`](#_advertise) address + This can also be set on client agents when used in combination with the [`translate_wan_addrs`](/consul/docs/agent/config/config-files#translate_wan_addrs) configuration option. By default, the [`-advertise`](#_advertise) address is advertised. However, in some cases all members of all datacenters cannot be on the same physical or virtual network, especially on hybrid setups mixing cloud and private datacenters. This flag enables server nodes gossiping through the public network for the WAN while using private VLANs for gossiping to each other and their client agents, and it allows client agents to be reached at this address when being - accessed from a remote datacenter if the remote datacenter is configured with [`translate_wan_addrs`](/docs/agent/config/config-files#translate_wan_addrs). In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr] + accessed from a remote datacenter if the remote datacenter is configured with [`translate_wan_addrs`](/consul/docs/agent/config/config-files#translate_wan_addrs). In Consul 1.1.0 and later this can be dynamically defined with a [go-sockaddr] template that is resolved at runtime. ## Address Bind Options @@ -264,7 +264,7 @@ information. ## Configuration File Options - `-config-file` ((#\_config_file)) - A configuration file to load. For - more information on the format of this file, read the [Configuration Files](/docs/agent/config/config-files) + more information on the format of this file, read the [Configuration Files](/consul/docs/agent/config/config-files) section. This option can be specified multiple times to load multiple configuration files. If it is specified multiple times, configuration files loaded later will merge with configuration files loaded earlier. During a config merge, single-value @@ -277,7 +277,7 @@ information. the [`config-file`](#_config_file) option above. This option can be specified multiple times to load multiple directories. Sub-directories of the config directory are not loaded. For more information on the format of the configuration files, see - the [Configuration Files](/docs/agent/config/config-files) section. + the [Configuration Files](/consul/docs/agent/config/config-files) section. - `-config-format` ((#\_config_format)) - The format of the configuration files to load. Normally, Consul detects the format of the config files from the @@ -304,7 +304,7 @@ information. - `-recursor` ((#\_recursor)) - Specifies the address of an upstream DNS server. This option may be provided multiple times, and is functionally equivalent - to the [`recursors` configuration option](/docs/agent/config/config-files#recursors). + to the [`recursors` configuration option](/consul/docs/agent/config/config-files#recursors). - `-join` ((#\_join)) - **Deprecated in Consul 1.15. This flag will be removed in a future version of Consul. Use the `-retry-join` flag instead.** This is an alias of [`-retry-join`](#_retry_join). @@ -321,9 +321,9 @@ information. This can be dynamically defined with a [go-sockaddr] template that is resolved at runtime. - If Consul is running on a non-default Serf LAN port, you must specify the port number in the address when using the `-retry-join` flag. Alternatively, you can specify the custom port number as the default in the agent's [`ports.serf_lan`](/docs/agent/config/config-files#serf_lan_port) configuration or with the [`-serf-lan-port`](#_serf_lan_port) command line flag when starting the agent. + If Consul is running on a non-default Serf LAN port, you must specify the port number in the address when using the `-retry-join` flag. Alternatively, you can specify the custom port number as the default in the agent's [`ports.serf_lan`](/consul/docs/agent/config/config-files#serf_lan_port) configuration or with the [`-serf-lan-port`](#_serf_lan_port) command line flag when starting the agent. - If your network contains network segments, refer to the [network segements documentation](/docs/enterprise/network-segments/create-network-segment) for additional information. + If your network contains network segments, refer to the [network segements documentation](/consul/docs/enterprise/network-segments/create-network-segment) for additional information. Here are some examples of using `-retry-join`: @@ -372,7 +372,7 @@ information. The `-retry-join` option accepts a unified interface using the [go-discover](https://github.com/hashicorp/go-discover) library for doing automatic cluster joining using cloud metadata. For more information, see - the [Cloud Auto-join page](/docs/install/cloud-auto-join). + the [Cloud Auto-join page](/consul/docs/install/cloud-auto-join). @@ -446,7 +446,7 @@ information. - `-log-level` ((#\_log_level)) - The level of logging to show after the Consul agent has started. This defaults to "info". The available log levels are "trace", "debug", "info", "warn", and "error". You can always connect to an agent - via [`consul monitor`](/commands/monitor) and use any log level. Also, + via [`consul monitor`](/consul/commands/monitor) and use any log level. Also, the log level can be changed during a config reload. - `-log-json` ((#\_log_json)) - This flag enables the agent to output logs diff --git a/website/content/docs/agent/config/config-files.mdx b/website/content/docs/agent/config/config-files.mdx index 45994d01c7..82053a9356 100644 --- a/website/content/docs/agent/config/config-files.mdx +++ b/website/content/docs/agent/config/config-files.mdx @@ -21,8 +21,8 @@ specified within it. Configuration files are used for more than just setting up the agent. They are also used to provide check and service definitions that announce the availability of system servers to the rest of the cluster. -These definitions are documented separately under [check configuration](/docs/discovery/checks) and -[service configuration](/docs/discovery/services) respectively. Service and check +These definitions are documented separately under [check configuration](/consul/docs/discovery/checks) and +[service configuration](/consul/docs/discovery/services) respectively. Service and check definitions support being updated during a reload. @@ -104,10 +104,10 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `grpc` - The gRPC API. Defaults to `client_addr` - `grpc_tls` - The gRPC API with TLS. Defaults to `client_addr` -- `alt_domain` Equivalent to the [`-alt-domain` command-line flag](/docs/agent/config/cli-flags#_alt_domain) +- `alt_domain` Equivalent to the [`-alt-domain` command-line flag](/consul/docs/agent/config/cli-flags#_alt_domain) - `audit` - Added in Consul 1.8, the audit object allow users to enable auditing - and configure a sink and filters for their audit logs. For more information, review the [audit log tutorial](https://learn.hashicorp.com/tutorials/consul/audit-logging). + and configure a sink and filters for their audit logs. For more information, review the [audit log tutorial](/consul/tutorials/datacenter-operations/audit-logging). @@ -182,8 +182,8 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." Consul servers. When these keys are provided as configuration, they will only be respected on bootstrapping. If they are not provided, the defaults will be used. In order to change the value of these options after bootstrapping, you will need - to use the [Consul Operator Autopilot](/commands/operator/autopilot) - command. For more information about Autopilot, review the [Autopilot tutorial](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations). + to use the [Consul Operator Autopilot](/consul/commands/operator/autopilot) + command. For more information about Autopilot, review the [Autopilot tutorial](/consul/tutorials/datacenter-operations/autopilot-datacenter-operations). The following sub-keys are available: @@ -254,7 +254,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `server_addresses` (Defaults to `[]`) This specifies the addresses of servers in the local datacenter to use for the initial RPC. These addresses support - [Cloud Auto-Joining](/docs/agent/config/cli-flags#cloud-auto-joining) and can optionally include a port to + [Cloud Auto-Joining](/consul/docs/agent/config/cli-flags#cloud-auto-joining) and can optionally include a port to use when making the outbound connection. If not port is provided the `server_port` will be used. @@ -272,7 +272,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `static` This object controls configuring the static authorizer setup in the Consul configuration file. Almost all sub-keys are identical to those provided by the [JWT - Auth Method](/docs/security/acl/auth-methods/jwt). + Auth Method](/consul/docs/security/acl/auth-methods/jwt). - `jwt_validation_pub_keys` (Defaults to `[]`) A list of PEM-encoded public keys to use to authenticate signatures locally. @@ -334,7 +334,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `claim_assertions` (Defaults to `[]`) List of assertions about the mapped claims required to authorize the incoming RPC request. The syntax uses [github.com/hashicorp/go-bexpr](https://github.com/hashicorp/go-bexpr) which is shared with the - [API filtering feature](/api-docs/features/filtering). For example, the following + [API filtering feature](/consul/api-docs/features/filtering). For example, the following configurations when combined will ensure that the JWT `sub` matches the node name requested by the client. @@ -370,9 +370,9 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `partition` - The admin partition name the client is requesting. -- `auto_reload_config` Equivalent to the [`-auto-reload-config` command-line flag](/docs/agent/config/cli-flags#_auto_reload_config). +- `auto_reload_config` Equivalent to the [`-auto-reload-config` command-line flag](/consul/docs/agent/config/cli-flags#_auto_reload_config). -- `bind_addr` Equivalent to the [`-bind` command-line flag](/docs/agent/config/cli-flags#_bind). +- `bind_addr` Equivalent to the [`-bind` command-line flag](/consul/docs/agent/config/cli-flags#_bind). This parameter can be set to a go-sockaddr template that resolves to a single address. Special characters such as backslashes `\` or double quotes `"` @@ -420,7 +420,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." changes state, the new state and associated output is synchronized immediately. To disable this behavior, set the value to "0s". -- `client_addr` Equivalent to the [`-client` command-line flag](/docs/agent/config/cli-flags#_client). +- `client_addr` Equivalent to the [`-client` command-line flag](/consul/docs/agent/config/cli-flags#_client). - `config_entries` This object allows setting options for centralized config entries. @@ -431,12 +431,12 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." the Consul server gains leadership. This option is only applicable to server nodes. Each bootstrap entry will be created only if it does not exist. When reloading, any new entries that have been added to the configuration will be processed. - See the [configuration entry docs](/docs/agent/config-entries) for more + See the [configuration entry docs](/consul/docs/agent/config-entries) for more details about the contents of each entry. -- `datacenter` Equivalent to the [`-datacenter` command-line flag](/docs/agent/config/cli-flags#_datacenter). +- `datacenter` Equivalent to the [`-datacenter` command-line flag](/consul/docs/agent/config/cli-flags#_datacenter). -- `data_dir` Equivalent to the [`-data-dir` command-line flag](/docs/agent/config/cli-flags#_data_dir). +- `data_dir` Equivalent to the [`-data-dir` command-line flag](/consul/docs/agent/config/cli-flags#_data_dir). - `disable_anonymous_signature` Disables providing an anonymous signature for de-duplication with the update check. See [`disable_update_check`](#disable_update_check). @@ -459,28 +459,28 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." `cert_file`, `ca_file`, `ca_path`, and `server_name`) to set up the client for HTTP or gRPC health checks. This allows services requiring 2-way TLS to be checked using the agent's credentials. This was added in Consul 1.0.1 and defaults to false. - `enable_central_service_config` When set, the Consul agent will look for any - [centralized service configuration](/docs/agent/config-entries) + [centralized service configuration](/consul/docs/agent/config-entries) that match a registering service instance. If it finds any, the agent will merge the centralized defaults with the service instance configuration. This allows for things like service protocol or proxy configuration to be defined centrally and inherited by any affected service registrations. This defaults to `false` in versions of Consul prior to 1.9.0, and defaults to `true` in Consul 1.9.0 and later. - `enable_debug` When set, enables some additional debugging features. Currently, this is only used to access runtime profiling HTTP endpoints, which are available with an `operator:read` ACL regardless of the value of `enable_debug`. -- `enable_script_checks` Equivalent to the [`-enable-script-checks` command-line flag](/docs/agent/config/cli-flags#_enable_script_checks). +- `enable_script_checks` Equivalent to the [`-enable-script-checks` command-line flag](/consul/docs/agent/config/cli-flags#_enable_script_checks). - ACLs must be enabled for agents and the `enable_script_checks` option must be set to `true` to enable script checks in Consul 0.9.0 and later. See [Registering and Querying Node Information](/docs/security/acl/acl-rules#registering-and-querying-node-information) for related information. + ACLs must be enabled for agents and the `enable_script_checks` option must be set to `true` to enable script checks in Consul 0.9.0 and later. See [Registering and Querying Node Information](/consul/docs/security/acl/acl-rules#registering-and-querying-node-information) for related information. ~> **Security Warning:** Enabling script checks in some configurations may introduce a known remote execution vulnerability targeted by malware. We strongly recommend `enable_local_script_checks` instead. Refer to the following article for additional guidance: [_Protecting Consul from RCE Risk in Specific Configurations_](https://www.hashicorp.com/blog/protecting-consul-from-rce-risk-in-specific-configurations) for more details. -- `enable_local_script_checks` Equivalent to the [`-enable-local-script-checks` command-line flag](/docs/agent/config/cli-flags#_enable_local_script_checks). +- `enable_local_script_checks` Equivalent to the [`-enable-local-script-checks` command-line flag](/consul/docs/agent/config/cli-flags#_enable_local_script_checks). - `disable_keyring_file` - Equivalent to the - [`-disable-keyring-file` command-line flag](/docs/agent/config/cli-flags#_disable_keyring_file). + [`-disable-keyring-file` command-line flag](/consul/docs/agent/config/cli-flags#_disable_keyring_file). -- `disable_coordinates` - Disables sending of [network coordinates](/docs/architecture/coordinates). +- `disable_coordinates` - Disables sending of [network coordinates](/consul/docs/architecture/coordinates). When network coordinates are disabled the `near` query param will not work to sort the nodes, - and the [`consul rtt`](/commands/rtt) command will not be able to provide round trip time between nodes. + and the [`consul rtt`](/consul/commands/rtt) command will not be able to provide round trip time between nodes. - `http_config` This object allows setting options for the HTTP API and UI. @@ -496,7 +496,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." only works with API endpoints, not `/ui` or `/debug`, those must be disabled with their respective configuration options. Any CLI commands that use disabled endpoints will no longer function as well. For more general access control, Consul's - [ACL system](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) + [ACL system](/consul/tutorials/security/access-control-setup-production) should be used, but this option is useful for removing access to HTTP API endpoints completely, or on specific agents. This is available in Consul 0.9.0 and later. @@ -526,13 +526,13 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `allow_write_http_from` This object is a list of networks in CIDR notation (eg "127.0.0.0/8") that are allowed to call the agent write endpoints. It defaults to an empty list, which means all networks are allowed. This is used to make the agent read-only, except for select ip ranges. - To block write calls from anywhere, use `[ "255.255.255.255/32" ]`. - To only allow write calls from localhost, use `[ "127.0.0.0/8" ]` - To only allow specific IPs, use `[ "10.0.0.1/32", "10.0.0.2/32" ]` - - `use_cache` ((#http_config_use_cache)) Defaults to true. If disabled, the agent won't be using [agent caching](/api-docs/features/caching) to answer the request. Even when the url parameter is provided. + - `use_cache` ((#http_config_use_cache)) Defaults to true. If disabled, the agent won't be using [agent caching](/consul/api-docs/features/caching) to answer the request. Even when the url parameter is provided. - `max_header_bytes` This setting controls the maximum number of bytes the consul http server will read parsing the request header's keys and values, including the request line. It does not limit the size of the request body. If zero, or negative, http.DefaultMaxHeaderBytes is used, which equates to 1 Megabyte. - `leave_on_terminate` If enabled, when the agent receives a TERM signal, it will send a `Leave` message to the rest of the cluster and gracefully leave. The default behavior for this feature varies based on whether or not the agent is running as a client or a server (prior to Consul 0.7 the default value was unconditionally set to `false`). On agents in client-mode, this defaults to `true` and for agents in server-mode, this defaults to `false`. -- `license_path` This specifies the path to a file that contains the Consul Enterprise license. Alternatively the license may also be specified in either the `CONSUL_LICENSE` or `CONSUL_LICENSE_PATH` environment variables. See the [licensing documentation](/docs/enterprise/license/overview) for more information about Consul Enterprise license management. Added in versions 1.10.0, 1.9.7 and 1.8.13. Prior to version 1.10.0 the value may be set for all agents to facilitate forwards compatibility with 1.10 but will only actually be used by client agents. +- `license_path` This specifies the path to a file that contains the Consul Enterprise license. Alternatively the license may also be specified in either the `CONSUL_LICENSE` or `CONSUL_LICENSE_PATH` environment variables. See the [licensing documentation](/consul/docs/enterprise/license/overview) for more information about Consul Enterprise license management. Added in versions 1.10.0, 1.9.7 and 1.8.13. Prior to version 1.10.0 the value may be set for all agents to facilitate forwards compatibility with 1.10 but will only actually be used by client agents. - `limits` Available in Consul 0.9.3 and later, this is a nested object that configures limits that are enforced by the agent. Prior to Consul 1.5.2, @@ -550,12 +550,12 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `rpc_max_conns_per_client` - Configures a limit of how many concurrent TCP connections a single source IP address is allowed to open to a single server. It affects both clients connections and other server connections. In general Consul clients multiplex many RPC calls over a single TCP connection so this can typically be kept low. It needs to be more than one though since servers open at least one additional connection for raft RPC, possibly more for WAN federation when using network areas, and snapshot requests from clients run over a separate TCP conn. A reasonably low limit significantly reduces the ability of an unauthenticated attacker to consume unbounded resources by holding open many connections. You may need to increase this if WAN federated servers connect via proxies or NAT gateways or similar causing many legitimate connections from a single source IP. Default value is `100` which is designed to be extremely conservative to limit issues with certain deployment patterns. Most deployments can probably reduce this safely. 100 connections on modern server hardware should not cause a significant impact on resource usage from an unauthenticated attacker though. - `rpc_rate` - Configures the RPC rate limiter on Consul _clients_ by setting the maximum request rate that this agent is allowed to make for RPC requests to Consul servers, in requests per second. Defaults to infinite, which disables rate limiting. - `rpc_max_burst` - The size of the token bucket used to recharge the RPC rate limiter on Consul _clients_. Defaults to 1000 tokens, and each token is good for a single RPC call to a Consul server. See https://en.wikipedia.org/wiki/Token_bucket for more details about how token bucket rate limiters operate. - - `kv_max_value_size` - **(Advanced)** Configures the maximum number of bytes for a kv request body to the [`/v1/kv`](/api-docs/kv) endpoint. This limit defaults to [raft's](https://github.com/hashicorp/raft) suggested max size (512KB). **Note that tuning these improperly can cause Consul to fail in unexpected ways**, it may potentially affect leadership stability and prevent timely heartbeat signals by increasing RPC IO duration. This option affects the txn endpoint too, but Consul 1.7.2 introduced `txn_max_req_len` which is the preferred way to set the limit for the txn endpoint. If both limits are set, the higher one takes precedence. - - `txn_max_req_len` - **(Advanced)** Configures the maximum number of bytes for a transaction request body to the [`/v1/txn`](/api-docs/txn) endpoint. This limit defaults to [raft's](https://github.com/hashicorp/raft) suggested max size (512KB). **Note that tuning these improperly can cause Consul to fail in unexpected ways**, it may potentially affect leadership stability and prevent timely heartbeat signals by increasing RPC IO duration. + - `kv_max_value_size` - **(Advanced)** Configures the maximum number of bytes for a kv request body to the [`/v1/kv`](/consul/api-docs/kv) endpoint. This limit defaults to [raft's](https://github.com/hashicorp/raft) suggested max size (512KB). **Note that tuning these improperly can cause Consul to fail in unexpected ways**, it may potentially affect leadership stability and prevent timely heartbeat signals by increasing RPC IO duration. This option affects the txn endpoint too, but Consul 1.7.2 introduced `txn_max_req_len` which is the preferred way to set the limit for the txn endpoint. If both limits are set, the higher one takes precedence. + - `txn_max_req_len` - **(Advanced)** Configures the maximum number of bytes for a transaction request body to the [`/v1/txn`](/consul/api-docs/txn) endpoint. This limit defaults to [raft's](https://github.com/hashicorp/raft) suggested max size (512KB). **Note that tuning these improperly can cause Consul to fail in unexpected ways**, it may potentially affect leadership stability and prevent timely heartbeat signals by increasing RPC IO duration. -- `default_query_time` Equivalent to the [`-default-query-time` command-line flag](/docs/agent/config/cli-flags#_default_query_time). +- `default_query_time` Equivalent to the [`-default-query-time` command-line flag](/consul/docs/agent/config/cli-flags#_default_query_time). -- `max_query_time` Equivalent to the [`-max-query-time` command-line flag](/docs/agent/config/cli-flags#_max_query_time). +- `max_query_time` Equivalent to the [`-max-query-time` command-line flag](/consul/docs/agent/config/cli-flags#_max_query_time). - `peering` This object allows setting options for cluster peering. @@ -569,27 +569,27 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `partition` - This flag is used to set the name of the admin partition the agent belongs to. An agent can only join and communicate with other agents within its admin partition. Review the - [Admin Partitions documentation](/docs/enterprise/admin-partitions) for more + [Admin Partitions documentation](/consul/docs/enterprise/admin-partitions) for more details. By default, this is an empty string, which is the `default` admin partition. This cannot be set on a server agent. ~> **Warning:** The `partition` option cannot be used either the - [`segment`](#segment-2) option or [`-segment`](/docs/agent/config/cli-flags#_segment) flag. + [`segment`](#segment-2) option or [`-segment`](/consul/docs/agent/config/cli-flags#_segment) flag. -- `performance` Available in Consul 0.7 and later, this is a nested object that allows tuning the performance of different subsystems in Consul. See the [Server Performance](/docs/install/performance) documentation for more details. The following parameters are available: +- `performance` Available in Consul 0.7 and later, this is a nested object that allows tuning the performance of different subsystems in Consul. See the [Server Performance](/consul/docs/install/performance) documentation for more details. The following parameters are available: - `leave_drain_time` - A duration that a server will dwell during a graceful leave in order to allow requests to be retried against other Consul servers. Under normal circumstances, this can prevent clients from experiencing "no leader" errors when performing a rolling update of the Consul servers. This was added in Consul 1.0. Must be a duration value such as 10s. Defaults to 5s. - `raft_multiplier` - An integer multiplier used by Consul servers to scale key Raft timing parameters. Omitting this value or setting it to 0 uses default timing described below. Lower values are used to tighten timing and increase sensitivity while higher values relax timings and reduce sensitivity. Tuning this affects the time it takes Consul to detect leader failures and to perform leader elections, at the expense of requiring more network and CPU resources for better performance. By default, Consul will use a lower-performance timing that's suitable - for [minimal Consul servers](/docs/install/performance#minimum), currently equivalent + for [minimal Consul servers](/consul/docs/install/performance#minimum), currently equivalent to setting this to a value of 5 (this default may be changed in future versions of Consul, depending if the target minimum server profile changes). Setting this to a value of 1 will configure Raft to its highest-performance mode, equivalent to the default timing of Consul - prior to 0.7, and is recommended for [production Consul servers](/docs/install/performance#production). + prior to 0.7, and is recommended for [production Consul servers](/consul/docs/install/performance#production). - See the note on [last contact](/docs/install/performance#production-server-requirements) timing for more + See the note on [last contact](/consul/docs/install/performance#production-server-requirements) timing for more details on tuning this parameter. The maximum allowed value is 10. - `rpc_hold_timeout` - A duration that a client @@ -598,7 +598,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." This was added in Consul 1.0. Must be a duration value such as 10s. Defaults to 7s. -- `pid_file` Equivalent to the [`-pid-file` command line flag](/docs/agent/config/cli-flags#_pid_file). +- `pid_file` Equivalent to the [`-pid-file` command line flag](/consul/docs/agent/config/cli-flags#_pid_file). - `ports` This is a nested object that allows setting the bind ports for the following keys: @@ -619,25 +619,25 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." tools to work automatically. `grpc_tls` is always guaranteed to be encrypted. Both `grpc` and `grpc_tls` can be configured at the same time, but they may not utilize the same port number. This field was added in Consul 1.14. - `serf_lan` ((#serf_lan_port)) - The Serf LAN port. Default 8301. TCP - and UDP. Equivalent to the [`-serf-lan-port` command line flag](/docs/agent/config/cli-flags#_serf_lan_port). + and UDP. Equivalent to the [`-serf-lan-port` command line flag](/consul/docs/agent/config/cli-flags#_serf_lan_port). - `serf_wan` ((#serf_wan_port)) - The Serf WAN port. Default 8302. - Equivalent to the [`-serf-wan-port` command line flag](/docs/agent/config/cli-flags#_serf_wan_port). Set + Equivalent to the [`-serf-wan-port` command line flag](/consul/docs/agent/config/cli-flags#_serf_wan_port). Set to -1 to disable. **Note**: this will disable WAN federation which is not recommended. Various catalog and WAN related endpoints will return errors or empty results. TCP and UDP. - `server` ((#server_rpc_port)) - Server RPC address. Default 8300. TCP only. - `sidecar_min_port` ((#sidecar_min_port)) - Inclusive minimum port number - to use for automatically assigned [sidecar service registrations](/docs/connect/registration/sidecar-service). + to use for automatically assigned [sidecar service registrations](/consul/docs/connect/registration/sidecar-service). Default 21000. Set to `0` to disable automatic port assignment. - `sidecar_max_port` ((#sidecar_max_port)) - Inclusive maximum port number - to use for automatically assigned [sidecar service registrations](/docs/connect/registration/sidecar-service). + to use for automatically assigned [sidecar service registrations](/consul/docs/connect/registration/sidecar-service). Default 21255. Set to `0` to disable automatic port assignment. - `expose_min_port` ((#expose_min_port)) - Inclusive minimum port number - to use for automatically assigned [exposed check listeners](/docs/connect/registration/service-registration#expose-paths-configuration-reference). + to use for automatically assigned [exposed check listeners](/consul/docs/connect/registration/service-registration#expose-paths-configuration-reference). Default 21500. Set to `0` to disable automatic port assignment. - `expose_max_port` ((#expose_max_port)) - Inclusive maximum port number - to use for automatically assigned [exposed check listeners](/docs/connect/registration/service-registration#expose-paths-configuration-reference). + to use for automatically assigned [exposed check listeners](/consul/docs/connect/registration/service-registration#expose-paths-configuration-reference). Default 21755. Set to `0` to disable automatic port assignment. - `primary_datacenter` - This designates the datacenter @@ -649,7 +649,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." enforcement of ACLs. - `primary_gateways` Equivalent to the [`-primary-gateway` - command-line flag](/docs/agent/config/cli-flags#_primary_gateway). Takes a list of addresses to use as the + command-line flag](/consul/docs/agent/config/cli-flags#_primary_gateway). Takes a list of addresses to use as the mesh gateways for the primary datacenter when authoritative replicated catalog data is not present. Discovery happens every [`primary_gateways_interval`](#primary_gateways_interval) until at least one primary mesh gateway is discovered. This was added in Consul @@ -660,7 +660,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." 30s. This was added in Consul 1.8.0. - `protocol` ((#protocol)) Equivalent to the [`-protocol` command-line - flag](/docs/agent/config/cli-flags#_protocol). + flag](/consul/docs/agent/config/cli-flags#_protocol). - `reap` This controls Consul's automatic reaping of child processes, which is useful if Consul is running as PID 1 in a Docker container. If this isn't @@ -702,13 +702,13 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." servers in all federated datacenters must have this enabled before any client can use [`use_streaming_backend`](#use_streaming_backend). -- `segment` - Equivalent to the [`-segment` command-line flag](/docs/agent/config/cli-flags#_segment). +- `segment` - Equivalent to the [`-segment` command-line flag](/consul/docs/agent/config/cli-flags#_segment). ~> **Warning:** The `segment` option cannot be used with the [`partition`](#partition-1) option. - `segments` - (Server agents only) This is a list of nested objects that specifies user-defined network segments, not including the `` segment, which is - created automatically. Refer to the [network segments documentation](/docs/enterprise/network-segments/create-network-segment)for additional information. + created automatically. Refer to the [network segments documentation](/consul/docs/enterprise/network-segments/create-network-segment)for additional information. for more details. - `name` ((#segment_name)) - The name of the segment. Must be a string @@ -718,18 +718,18 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `port` ((#segment_port)) - The port to use for the segment's gossip layer (required). - `advertise` ((#segment_advertise)) - The advertise address to use for - the segment's gossip layer. Defaults to the [`-advertise`](/docs/agent/config/cli-flags#_advertise) value + the segment's gossip layer. Defaults to the [`-advertise`](/consul/docs/agent/config/cli-flags#_advertise) value if not provided. - `rpc_listener` ((#segment_rpc_listener)) - If true, a separate RPC - listener will be started on this segment's [`-bind`](/docs/agent/config/cli-flags#_bind) address on the rpc - port. Only valid if the segment's bind address differs from the [`-bind`](/docs/agent/config/cli-flags#_bind) + listener will be started on this segment's [`-bind`](/consul/docs/agent/config/cli-flags#_bind) address on the rpc + port. Only valid if the segment's bind address differs from the [`-bind`](/consul/docs/agent/config/cli-flags#_bind) address. Defaults to false. -- `server` Equivalent to the [`-server` command-line flag](/docs/agent/config/cli-flags#_server). +- `server` Equivalent to the [`-server` command-line flag](/consul/docs/agent/config/cli-flags#_server). - `non_voting_server` - **This field is deprecated in Consul 1.9.1. See the [`read_replica`](#read_replica) field instead.** -- `read_replica` - Equivalent to the [`-read-replica` command-line flag](/docs/agent/config/cli-flags#_read_replica). +- `read_replica` - Equivalent to the [`-read-replica` command-line flag](/consul/docs/agent/config/cli-flags#_read_replica). - `session_ttl_min` The minimum allowed session TTL. This ensures sessions are not created with TTLs shorter than the specified limit. It is recommended to keep this limit at or above @@ -747,26 +747,26 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." a client will gracefully leave). - `translate_wan_addrs` If set to true, Consul - will prefer a node's configured [WAN address](/docs/agent/config/cli-flags#_advertise-wan) + will prefer a node's configured [WAN address](/consul/docs/agent/config/cli-flags#_advertise-wan) when servicing DNS and HTTP requests for a node in a remote datacenter. This allows the node to be reached within its own datacenter using its local address, and reached from other datacenters using its WAN address, which is useful in hybrid setups with mixed networks. This is disabled by default. Starting in Consul 0.7 and later, node addresses in responses to HTTP requests will also prefer a - node's configured [WAN address](/docs/agent/config/cli-flags#_advertise-wan) when querying for a node in a remote - datacenter. An [`X-Consul-Translate-Addresses`](/api-docs/api-structure#translated-addresses) header + node's configured [WAN address](/consul/docs/agent/config/cli-flags#_advertise-wan) when querying for a node in a remote + datacenter. An [`X-Consul-Translate-Addresses`](/consul/api-docs/api-structure#translated-addresses) header will be present on all responses when translation is enabled to help clients know that the addresses may be translated. The `TaggedAddresses` field in responses also have a `lan` address for clients that need knowledge of that address, regardless of translation. The following endpoints translate addresses: - - [`/v1/catalog/nodes`](/api-docs/catalog#list-nodes) - - [`/v1/catalog/node/`](/api-docs/catalog#retrieve-map-of-services-for-a-node) - - [`/v1/catalog/service/`](/api-docs/catalog#list-nodes-for-service) - - [`/v1/health/service/`](/api-docs/health#list-nodes-for-service) - - [`/v1/query//execute`](/api-docs/query#execute-prepared-query) + - [`/v1/catalog/nodes`](/consul/api-docs/catalog#list-nodes) + - [`/v1/catalog/node/`](/consul/api-docs/catalog#retrieve-map-of-services-for-a-node) + - [`/v1/catalog/service/`](/consul/api-docs/catalog#list-nodes-for-service) + - [`/v1/health/service/`](/consul/api-docs/health#list-nodes-for-service) + - [`/v1/query//execute`](/consul/api-docs/query#execute-prepared-query) - `unix_sockets` - This allows tuning the ownership and permissions of the Unix domain socket files created by Consul. Domain sockets are @@ -793,7 +793,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `watches` - Watches is a list of watch specifications which allow an external process to be automatically invoked when a particular data view - is updated. See the [watch documentation](/docs/dynamic-app-config/watches) for more detail. + is updated. See the [watch documentation](/consul/docs/dynamic-app-config/watches) for more detail. Watches can be modified when the configuration is reloaded. ## ACL Parameters @@ -853,8 +853,8 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `enable_token_replication` ((#acl_enable_token_replication)) - By default secondary Consul datacenters will perform replication of only ACL policies and roles. Setting this configuration will will enable ACL token replication and - allow for the creation of both [local tokens](/api-docs/acl/tokens#local) and - [auth methods](/docs/security/acl/auth-methods) in connected secondary datacenters. + allow for the creation of both [local tokens](/consul/api-docs/acl/tokens#local) and + [auth methods](/consul/docs/security/acl/auth-methods) in connected secondary datacenters. ~> **Warning:** When enabling ACL token replication on the secondary datacenter, global tokens already present in the secondary datacenter will be lost. For @@ -890,10 +890,10 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `default` ((#acl_tokens_default)) - When provided, this agent will use this token by default when making requests to the Consul servers - instead of the [anonymous token](/docs/security/acl/acl-tokens#anonymous-token). + instead of the [anonymous token](/consul/docs/security/acl/acl-tokens#anonymous-token). Consul HTTP API requests can provide an alternate token in their authorization header to override the `default` or anonymous token on a per-request basis, - as described in [HTTP API Authentication](/api-docs/api-structure#authentication). + as described in [HTTP API Authentication](/consul/api-docs/api-structure#authentication). - `agent` ((#acl_tokens_agent)) - Used for clients and servers to perform internal operations. If this isn't specified, then the @@ -906,7 +906,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `agent_recovery` ((#acl_tokens_agent_recovery)) - This is available in Consul 1.11 and later. In prior versions, use [`acl.tokens.agent_master`](#acl_tokens_agent_master). - Used to access [agent endpoints](/api-docs/agent) that require agent read or write privileges, + Used to access [agent endpoints](/consul/api-docs/agent) that require agent read or write privileges, or node read privileges, even if Consul servers aren't present to validate any tokens. This should only be used by operators during outages, regular ACL tokens should normally be used by applications. @@ -916,7 +916,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `config_file_service_registration` ((#acl_tokens_config_file_service_registration)) - The ACL token this agent uses to register services and checks from [service - definitions](/docs/discovery/services) and [check definitions](/docs/discovery/checks) found + definitions](/consul/docs/discovery/services) and [check definitions](/consul/docs/discovery/checks) found in configuration files or in configuration fragments passed to the agent using the `-hcl` flag. @@ -931,14 +931,14 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." services "A" and "B" in order to successfully register both services. If the token is missing `service:write` permissions for service "B", the agent will successfully register service "A" and fail to register service "B". Failed registration requests are eventually retried as part - of [anti-entropy enforcement](/docs/architecture/anti-entropy). If a registration request is + of [anti-entropy enforcement](/consul/docs/architecture/anti-entropy). If a registration request is failing due to missing permissions, the the token for this agent can be updated with additional policy rules or the `config_file_service_registration` token can be replaced using - the [Set Agent Token](/commands/acl/set-agent-token) CLI command. + the [Set Agent Token](/consul/commands/acl/set-agent-token) CLI command. - `replication` ((#acl_tokens_replication)) - The ACL token used to authorize secondary datacenters with the primary datacenter for replication - operations. This token is required for servers outside the [`primary_datacenter`](#primary_datacenter) when ACLs are enabled. This token may be provided later using the [agent token API](/api-docs/agent#update-acl-tokens) on each server. This token must have at least "read" permissions on ACL data but if ACL token replication is enabled then it must have "write" permissions. This also enables Connect replication, for which the token will require both operator "write" and intention "read" permissions for replicating CA and Intention data. + operations. This token is required for servers outside the [`primary_datacenter`](#primary_datacenter) when ACLs are enabled. This token may be provided later using the [agent token API](/consul/api-docs/agent#update-acl-tokens) on each server. This token must have at least "read" permissions on ACL data but if ACL token replication is enabled then it must have "write" permissions. This also enables Connect replication, for which the token will require both operator "write" and intention "read" permissions for replicating CA and Intention data. ~> **Warning:** When enabling ACL token replication on the secondary datacenter, policies and roles already present in the secondary datacenter will be lost. For @@ -972,7 +972,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." This designates the datacenter which is authoritative for ACL information. It must be provided to enable ACLs. All servers and datacenters must agree on the ACL datacenter. Setting it on the servers is all you need for cluster-level enforcement, but for the APIs to forward properly from the clients, it must be set on them too. In Consul 0.8 and later, this also enables agent-level enforcement - of ACLs. Please review the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) for more details. + of ACLs. Please review the [ACL tutorial](/consul/tutorials/security/access-control-setup-production) for more details. - `acl_default_policy` ((#acl_default_policy_legacy)) - **Deprecated in Consul 1.4.0. See the [`acl.default_policy`](#acl_default_policy) field instead.** Either "allow" or "deny"; defaults to "allow". The default policy controls the @@ -995,7 +995,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `acl_agent_master_token` ((#acl_agent_master_token_legacy)) - **Deprecated in Consul 1.4.0. See the [`acl.tokens.agent_master`](#acl_tokens_agent_master) - field instead.** Used to access [agent endpoints](/api-docs/agent) that + field instead.** Used to access [agent endpoints](/consul/api-docs/agent) that require agent read or write privileges, or node read privileges, even if Consul servers aren't present to validate any tokens. This should only be used by operators during outages, regular ACL tokens should normally be used by applications. This @@ -1022,16 +1022,16 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `acl_replication_token` ((#acl_replication_token_legacy)) - **Deprecated in Consul 1.4.0. See the [`acl.tokens.replication`](#acl_tokens_replication) field instead.** Only used for servers outside the [`primary_datacenter`](#primary_datacenter) - running Consul 0.7 or later. When provided, this will enable [ACL replication](https://learn.hashicorp.com/tutorials/consul/access-control-replication-multiple-datacenters) + running Consul 0.7 or later. When provided, this will enable [ACL replication](/consul/tutorials/security-operations/access-control-replication-multiple-datacenters) using this ACL replication using this token to retrieve and replicate the ACLs to the non-authoritative local datacenter. In Consul 0.9.1 and later you can enable ACL replication using [`acl.enable_token_replication`](#acl_enable_token_replication) and then - set the token later using the [agent token API](/api-docs/agent#update-acl-tokens) + set the token later using the [agent token API](/consul/api-docs/agent#update-acl-tokens) on each server. If the `acl_replication_token` is set in the config, it will automatically set [`acl.enable_token_replication`](#acl_enable_token_replication) to true for backward compatibility. If there's a partition or other outage affecting the authoritative datacenter, and the - [`acl_down_policy`](/docs/agent/config/config-files#acl_down_policy) is set to "extend-cache", tokens not + [`acl_down_policy`](/consul/docs/agent/config/config-files#acl_down_policy) is set to "extend-cache", tokens not in the cache can be resolved during the outage using the replicated set of ACLs. - `acl_token` ((#acl_token_legacy)) - **Deprecated in Consul 1.4.0. See @@ -1047,7 +1047,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `enable_acl_replication` **Deprecated in Consul 1.11. Use the [`acl.enable_token_replication`](#acl_enable_token_replication) field instead.** When set on a Consul server, enables ACL replication without having to set the replication token via [`acl_replication_token`](#acl_replication_token). Instead, enable ACL replication - and then introduce the token using the [agent token API](/api-docs/agent#update-acl-tokens) on each server. + and then introduce the token using the [agent token API](/consul/api-docs/agent#update-acl-tokens) on each server. See [`acl_replication_token`](#acl_replication_token) for more details. ~> **Warning:** When enabling ACL token replication on the secondary datacenter, @@ -1057,13 +1057,13 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." ## Advertise Address Parameters -- `advertise_addr` Equivalent to the [`-advertise` command-line flag](/docs/agent/config/cli-flags#_advertise). +- `advertise_addr` Equivalent to the [`-advertise` command-line flag](/consul/docs/agent/config/cli-flags#_advertise). - `advertise_addr_ipv4` This was added together with [`advertise_addr_ipv6`](#advertise_addr_ipv6) to support dual stack IPv4/IPv6 environments. Using this, both IPv4 and IPv6 addresses can be specified and requested during eg service discovery. - `advertise_addr_ipv6` This was added together with [`advertise_addr_ipv4`](#advertise_addr_ipv4) to support dual stack IPv4/IPv6 environments. Using this, both IPv4 and IPv6 addresses can be specified and requested during eg service discovery. -- `advertise_addr_wan` Equivalent to the [`-advertise-wan` command-line flag](/docs/agent/config/cli-flags#_advertise-wan). +- `advertise_addr_wan` Equivalent to the [`-advertise-wan` command-line flag](/consul/docs/agent/config/cli-flags#_advertise-wan). - `advertise_addr_wan_ipv4` This was added together with [`advertise_addr_wan_ipv6`](#advertise_addr_wan_ipv6) to support dual stack IPv4/IPv6 environments. Using this, both IPv4 and IPv6 addresses can be specified and requested during eg service discovery. @@ -1076,9 +1076,9 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." ## Bootstrap Parameters -- `bootstrap` Equivalent to the [`-bootstrap` command-line flag](/docs/agent/config/cli-flags#_bootstrap). +- `bootstrap` Equivalent to the [`-bootstrap` command-line flag](/consul/docs/agent/config/cli-flags#_bootstrap). -- `bootstrap_expect` Equivalent to the [`-bootstrap-expect` command-line flag](/docs/agent/config/cli-flags#_bootstrap_expect). +- `bootstrap_expect` Equivalent to the [`-bootstrap-expect` command-line flag](/consul/docs/agent/config/cli-flags#_bootstrap_expect). ## Connect Parameters @@ -1097,12 +1097,12 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `ca_provider` ((#connect_ca_provider)) Controls which CA provider to use for Connect's CA. Currently only the `aws-pca`, `consul`, and `vault` providers are supported. This is only used when initially bootstrapping the cluster. For an existing cluster, - use the [Update CA Configuration Endpoint](/api-docs/connect/ca#update-ca-configuration). + use the [Update CA Configuration Endpoint](/consul/api-docs/connect/ca#update-ca-configuration). - `ca_config` ((#connect_ca_config)) An object which allows setting different config options based on the CA provider chosen. This is only used when initially bootstrapping the cluster. For an existing cluster, use the [Update CA Configuration - Endpoint](/api-docs/connect/ca#update-ca-configuration). + Endpoint](/consul/api-docs/connect/ca#update-ca-configuration). The following providers are supported: @@ -1126,7 +1126,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." connect to. - `token` ((#vault_ca_token)) The Vault token to use. In Consul 1.8.5 and later, if - the token has the [renewable](https://www.vaultproject.io/api-docs/auth/token#renewable) + the token has the [renewable](/vault/api-docs/auth/token#renewable) flag set, Consul will attempt to renew its lease periodically after half the duration has expired. @@ -1146,7 +1146,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `auth_method` ((#vault_ca_auth_method)) Vault auth method to use for logging in to Vault. - Please see [Vault Auth Methods](https://www.vaultproject.io/docs/auth) for more information + Please see [Vault Auth Methods](/vault/docs/auth) for more information on how to configure individual auth methods. If auth method is provided, Consul will obtain a new token from Vault when the token can no longer be renewed. @@ -1156,7 +1156,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." If not provided the auth method type will be used as the mount path. - `params` The parameters to configure the auth method. - Please see [Vault Auth Methods](https://www.vaultproject.io/docs/auth) for information on how + Please see [Vault Auth Methods](/vault/docs/auth) for information on how to configure the auth method you wish to use. If using the Kubernetes auth method, Consul will read the service account token from the default mount path `/var/run/secrets/kubernetes.io/serviceaccount/token` if the `jwt` parameter is not provided. @@ -1253,7 +1253,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." ## DNS and Domain Parameters - `dns_config` This object allows a number of sub-keys - to be set which can tune how DNS queries are serviced. Check the tutorial on [DNS caching](https://learn.hashicorp.com/tutorials/consul/dns-caching) for more detail. + to be set which can tune how DNS queries are serviced. Check the tutorial on [DNS caching](/consul/tutorials/networking/dns-caching) for more detail. The following sub-keys are available: @@ -1355,25 +1355,25 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." in seconds, default value is 600, ie: 10 minutes. - `use_cache` ((#dns_use_cache)) - When set to true, DNS resolution will - use the agent cache described in [agent caching](/api-docs/features/caching). + use the agent cache described in [agent caching](/consul/api-docs/features/caching). This setting affects all service and prepared queries DNS requests. Implies [`allow_stale`](#allow_stale) - `cache_max_age` ((#dns_cache_max_age)) - When [use_cache](#dns_use_cache) is enabled, the agent will attempt to re-fetch the result from the servers if - the cached value is older than this duration. See: [agent caching](/api-docs/features/caching). + the cached value is older than this duration. See: [agent caching](/consul/api-docs/features/caching). **Note** that unlike the `max-age` HTTP header, a value of 0 for this field is equivalent to "no max age". To get a fresh value from the cache use a very small value of `1ns` instead of 0. - `prefer_namespace` ((#dns_prefer_namespace)) **Deprecated in Consul 1.11. - Use the [canonical DNS format for enterprise service lookups](/docs/discovery/dns#service-lookups-for-consul-enterprise) instead.** - + Use the [canonical DNS format for enterprise service lookups](/consul/docs/discovery/dns#service-lookups-for-consul-enterprise) instead.** - When set to `true`, in a DNS query for a service, a single label between the domain and the `service` label is treated as a namespace name instead of a datacenter. When set to `false`, the default, the behavior is the same as non-Enterprise versions and treats the single label as the datacenter. -- `domain` Equivalent to the [`-domain` command-line flag](/docs/agent/config/cli-flags#_domain). +- `domain` Equivalent to the [`-domain` command-line flag](/consul/docs/agent/config/cli-flags#_domain). ## Encryption Parameters @@ -1416,18 +1416,18 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." the certificates requested by `auto_encrypt` from the server have these `ip_san` set as IP SAN. -- `encrypt` Equivalent to the [`-encrypt` command-line flag](/docs/agent/config/cli-flags#_encrypt). +- `encrypt` Equivalent to the [`-encrypt` command-line flag](/consul/docs/agent/config/cli-flags#_encrypt). - `encrypt_verify_incoming` - This is an optional parameter that can be used to disable enforcing encryption for incoming gossip in order to upshift from unencrypted to encrypted gossip on a running cluster. - See [this section](/docs/security/encryption#configuring-gossip-encryption-on-an-existing-cluster) + See [this section](/consul/docs/security/encryption#configuring-gossip-encryption-on-an-existing-cluster) for more information. Defaults to true. - `encrypt_verify_outgoing` - This is an optional parameter that can be used to disable enforcing encryption for outgoing gossip in order to upshift from unencrypted to encrypted gossip on a running cluster. - See [this section](/docs/security/encryption#configuring-gossip-encryption-on-an-existing-cluster) + See [this section](/consul/docs/security/encryption#configuring-gossip-encryption-on-an-existing-cluster) for more information. Defaults to true. ## Gossip Parameters @@ -1518,39 +1518,39 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." ## Join Parameters -- `rejoin_after_leave` Equivalent to the [`-rejoin` command-line flag](/docs/agent/config/cli-flags#_rejoin). +- `rejoin_after_leave` Equivalent to the [`-rejoin` command-line flag](/consul/docs/agent/config/cli-flags#_rejoin). -- `retry_join` - Equivalent to the [`-retry-join`](/docs/agent/config/cli-flags#retry-join) command-line flag. +- `retry_join` - Equivalent to the [`-retry-join`](/consul/docs/agent/config/cli-flags#retry-join) command-line flag. -- `retry_interval` Equivalent to the [`-retry-interval` command-line flag](/docs/agent/config/cli-flags#_retry_interval). +- `retry_interval` Equivalent to the [`-retry-interval` command-line flag](/consul/docs/agent/config/cli-flags#_retry_interval). -- `retry_max` - Equivalent to the [`-retry-max`](/docs/agent/config/cli-flags#_retry_max) command-line flag. +- `retry_max` - Equivalent to the [`-retry-max`](/consul/docs/agent/config/cli-flags#_retry_max) command-line flag. -- `retry_join_wan` Equivalent to the [`-retry-join-wan` command-line flag](/docs/agent/config/cli-flags#_retry_join_wan). Takes a list of addresses to attempt joining to WAN every [`retry_interval_wan`](#_retry_interval_wan) until at least one join works. +- `retry_join_wan` Equivalent to the [`-retry-join-wan` command-line flag](/consul/docs/agent/config/cli-flags#_retry_join_wan). Takes a list of addresses to attempt joining to WAN every [`retry_interval_wan`](#_retry_interval_wan) until at least one join works. -- `retry_interval_wan` Equivalent to the [`-retry-interval-wan` command-line flag](/docs/agent/config/cli-flags#_retry_interval_wan). +- `retry_interval_wan` Equivalent to the [`-retry-interval-wan` command-line flag](/consul/docs/agent/config/cli-flags#_retry_interval_wan). -- `start_join` **Deprecated in Consul 1.15. Use the [`retry_join`](/docs/agent/config/config-files#retry_join) field instead. This field will be removed in a future version of Consul.** +- `start_join` **Deprecated in Consul 1.15. Use the [`retry_join`](/consul/docs/agent/config/config-files#retry_join) field instead. This field will be removed in a future version of Consul.** This field is an alias of `retry_join`. -- `start_join_wan` **Deprecated in Consul 1.15. Use the [`retry_join_wan`](/docs/agent/config/config-files#retry_join_wan) field instead. This field will be removed in a future version of Consul.** +- `start_join_wan` **Deprecated in Consul 1.15. Use the [`retry_join_wan`](/consul/docs/agent/config/config-files#retry_join_wan) field instead. This field will be removed in a future version of Consul.** This field is an alias of `retry_join_wan`. ## Log Parameters -- `log_file` Equivalent to the [`-log-file` command-line flag](/docs/agent/config/cli-flags#_log_file). +- `log_file` Equivalent to the [`-log-file` command-line flag](/consul/docs/agent/config/cli-flags#_log_file). -- `log_rotate_duration` Equivalent to the [`-log-rotate-duration` command-line flag](/docs/agent/config/cli-flags#_log_rotate_duration). +- `log_rotate_duration` Equivalent to the [`-log-rotate-duration` command-line flag](/consul/docs/agent/config/cli-flags#_log_rotate_duration). -- `log_rotate_bytes` Equivalent to the [`-log-rotate-bytes` command-line flag](/docs/agent/config/cli-flags#_log_rotate_bytes). +- `log_rotate_bytes` Equivalent to the [`-log-rotate-bytes` command-line flag](/consul/docs/agent/config/cli-flags#_log_rotate_bytes). -- `log_rotate_max_files` Equivalent to the [`-log-rotate-max-files` command-line flag](/docs/agent/config/cli-flags#_log_rotate_max_files). +- `log_rotate_max_files` Equivalent to the [`-log-rotate-max-files` command-line flag](/consul/docs/agent/config/cli-flags#_log_rotate_max_files). -- `log_level` Equivalent to the [`-log-level` command-line flag](/docs/agent/config/cli-flags#_log_level). +- `log_level` Equivalent to the [`-log-level` command-line flag](/consul/docs/agent/config/cli-flags#_log_level). -- `log_json` Equivalent to the [`-log-json` command-line flag](/docs/agent/config/cli-flags#_log_json). +- `log_json` Equivalent to the [`-log-json` command-line flag](/consul/docs/agent/config/cli-flags#_log_json). -- `enable_syslog` Equivalent to the [`-syslog` command-line flag](/docs/agent/config/cli-flags#_syslog). +- `enable_syslog` Equivalent to the [`-syslog` command-line flag](/consul/docs/agent/config/cli-flags#_syslog). - `syslog_facility` When [`enable_syslog`](#enable_syslog) is provided, this controls to which facility messages are sent. By default, `LOCAL0` @@ -1558,11 +1558,11 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." ## Node Parameters -- `node_id` Equivalent to the [`-node-id` command-line flag](/docs/agent/config/cli-flags#_node_id). +- `node_id` Equivalent to the [`-node-id` command-line flag](/consul/docs/agent/config/cli-flags#_node_id). -- `node_name` Equivalent to the [`-node` command-line flag](/docs/agent/config/cli-flags#_node). +- `node_name` Equivalent to the [`-node` command-line flag](/consul/docs/agent/config/cli-flags#_node). -- `node_meta` Available in Consul 0.7.3 and later, This object allows associating arbitrary metadata key/value pairs with the local node, which can then be used for filtering results from certain catalog endpoints. See the [`-node-meta` command-line flag](/docs/agent/config/cli-flags#_node_meta) for more information. +- `node_meta` Available in Consul 0.7.3 and later, This object allows associating arbitrary metadata key/value pairs with the local node, which can then be used for filtering results from certain catalog endpoints. See the [`-node-meta` command-line flag](/consul/docs/agent/config/cli-flags#_node_meta) for more information. @@ -1582,7 +1582,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." -- `disable_host_node_id` Equivalent to the [`-disable-host-node-id` command-line flag](/docs/agent/config/cli-flags#_disable_host_node_id). +- `disable_host_node_id` Equivalent to the [`-disable-host-node-id` command-line flag](/consul/docs/agent/config/cli-flags#_disable_host_node_id). ## Raft Parameters @@ -1597,7 +1597,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `raft_protocol` ((#raft_protocol)) Equivalent to the [`-raft-protocol` - command-line flag](/docs/agent/config/cli-flags#_raft_protocol). + command-line flag](/consul/docs/agent/config/cli-flags#_raft_protocol). - `raft_snapshot_threshold` ((#\_raft_snapshot_threshold)) This controls the minimum number of raft commit entries between snapshots that are saved to @@ -1646,14 +1646,14 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." ## Serf Parameters -- `serf_lan` ((#serf_lan_bind)) Equivalent to the [`-serf-lan-bind` command-line flag](/docs/agent/config/cli-flags#_serf_lan_bind). +- `serf_lan` ((#serf_lan_bind)) Equivalent to the [`-serf-lan-bind` command-line flag](/consul/docs/agent/config/cli-flags#_serf_lan_bind). This is an IP address, not to be confused with [`ports.serf_lan`](#serf_lan_port). -- `serf_lan_allowed_cidrs` ((#serf_lan_allowed_cidrs)) Equivalent to the [`-serf-lan-allowed-cidrs` command-line flag](/docs/agent/config/cli-flags#_serf_lan_allowed_cidrs). +- `serf_lan_allowed_cidrs` ((#serf_lan_allowed_cidrs)) Equivalent to the [`-serf-lan-allowed-cidrs` command-line flag](/consul/docs/agent/config/cli-flags#_serf_lan_allowed_cidrs). -- `serf_wan` ((#serf_wan_bind)) Equivalent to the [`-serf-wan-bind` command-line flag](/docs/agent/config/cli-flags#_serf_wan_bind). +- `serf_wan` ((#serf_wan_bind)) Equivalent to the [`-serf-wan-bind` command-line flag](/consul/docs/agent/config/cli-flags#_serf_wan_bind). -- `serf_wan_allowed_cidrs` ((#serf_wan_allowed_cidrs)) Equivalent to the [`-serf-wan-allowed-cidrs` command-line flag](/docs/agent/config/cli-flags#_serf_wan_allowed_cidrs). +- `serf_wan_allowed_cidrs` ((#serf_wan_allowed_cidrs)) Equivalent to the [`-serf-wan-allowed-cidrs` command-line flag](/consul/docs/agent/config/cli-flags#_serf_wan_allowed_cidrs). ## Telemetry Parameters @@ -1778,7 +1778,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." 2 times the interval of scrape of Prometheus, but you might also put a very high retention time such as a few days (for instance 744h to enable retention to 31 days). Fetching the metrics using prometheus can then be performed using the - [`/v1/agent/metrics?format=prometheus`](/api-docs/agent#view-metrics) endpoint. + [`/v1/agent/metrics?format=prometheus`](/consul/api-docs/agent#view-metrics) endpoint. The format is compatible natively with prometheus. When running in this mode, it is recommended to also enable the option [`disable_hostname`](#telemetry-disable_hostname) to avoid having prefixed metrics with hostname. Consul does not use the default @@ -1811,7 +1811,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." ## UI Parameters - `ui` - **This field is deprecated in Consul 1.9.0. See the [`ui_config.enabled`](#ui_config_enabled) field instead.** - Equivalent to the [`-ui`](/docs/agent/config/cli-flags#_ui) command-line flag. + Equivalent to the [`-ui`](/consul/docs/agent/config/cli-flags#_ui) command-line flag. - `ui_config` - This object allows a number of sub-keys to be set which controls the display or features available in the UI. Configuring the UI with this @@ -1822,16 +1822,16 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `enabled` ((#ui_config_enabled)) - This enables the service of the web UI from this agent. Boolean value, defaults to false. In `-dev` mode this defaults to true. Replaces `ui` from before 1.9.0. Equivalent to the - [`-ui`](/docs/agent/config/cli-flags#_ui) command-line flag. + [`-ui`](/consul/docs/agent/config/cli-flags#_ui) command-line flag. - `dir` ((#ui_config_dir)) - This specifies that the web UI should be served from an external dir rather than the build in one. This allows for customization or development. Replaces `ui_dir` from before 1.9.0. - Equivalent to the [`-ui-dir`](/docs/agent/config/cli-flags#_ui_dir) command-line flag. + Equivalent to the [`-ui-dir`](/consul/docs/agent/config/cli-flags#_ui_dir) command-line flag. - `content_path` ((#ui_config_content_path)) - This specifies the HTTP path that the web UI should be served from. Defaults to `/ui/`. Equivalent to the - [`-ui-content-path`](/docs/agent/config/cli-flags#_ui_content_path) flag. + [`-ui-content-path`](/consul/docs/agent/config/cli-flags#_ui_content_path) flag. - `metrics_provider` ((#ui_config_metrics_provider)) - Specifies a named metrics provider implementation the UI should use to fetch service metrics. @@ -1870,7 +1870,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." **this might make it possible for a malicious user on the network to query for arbitrary metrics about any server or workload in your infrastructure, or overload the metrics infrastructure with queries**. See [Metrics Proxy - Security](/docs/connect/observability/ui-visualization#metrics-proxy-security) + Security](/consul/docs/connect/observability/ui-visualization#metrics-proxy-security) for more details. The following sub-keys are available: @@ -1889,10 +1889,10 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." `base_url`. It defaults to `["/api/v1/query_range", "/api/v1/query"]` which are the endpoints required for the built-in Prometheus provider. If a [custom - provider](/docs/connect/observability/ui-visualization#custom-metrics-providers) + provider](/consul/docs/connect/observability/ui-visualization#custom-metrics-providers) is used that requires the metrics proxy, the correct allowlist must be specified to enable proxying to necessary endpoints. See [Path - Allowlist](/docs/connect/observability/ui-visualization#path-allowlist) + Allowlist](/consul/docs/connect/observability/ui-visualization#path-allowlist) for more information. - `add_headers` ((#ui_config_metrics_proxy_add_headers)) - This is an @@ -1918,14 +1918,14 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." available are listed for each template. For more information and examples see [UI - Visualization](/docs/connect/observability/ui-visualization#configuring-dashboard-urls) + Visualization](/consul/docs/connect/observability/ui-visualization#configuring-dashboard-urls) The following named templates are defined: - `service` ((#ui_config_dashboard_url_templates_service)) - This is the URL to use when linking to the dashboard for a specific service. It is shown as part of the [Topology - Visualization](/docs/connect/observability/ui-visualization). + Visualization](/consul/docs/connect/observability/ui-visualization). The placeholders available are: @@ -1936,7 +1936,7 @@ Valid time units are 'ns', 'us' (or 'µs'), 'ms', 's', 'm', 'h'." - `{{Datacenter}}` - Replaced with the current service's datacenter. - `ui_dir` - **This field is deprecated in Consul 1.9.0. See the [`ui_config.dir`](#ui_config_dir) field instead.** - Equivalent to the [`-ui-dir`](/docs/agent/config/cli-flags#_ui_dir) command-line + Equivalent to the [`-ui-dir`](/consul/docs/agent/config/cli-flags#_ui_dir) command-line flag. This configuration key is not required as of Consul version 0.7.0 and later. Specifying this configuration key will enable the web UI. There is no need to specify both ui-dir and ui. Specifying both will result in an error. diff --git a/website/content/docs/agent/config/index.mdx b/website/content/docs/agent/config/index.mdx index d1862ab47f..b2e3ac42c8 100644 --- a/website/content/docs/agent/config/index.mdx +++ b/website/content/docs/agent/config/index.mdx @@ -14,8 +14,8 @@ descriptions. Configuration precedence is evaluated in the following order: -1. [Command line arguments](/docs/agent/config/cli-flags) -2. [Configuration files](/docs/agent/config/config-files) +1. [Command line arguments](/consul/docs/agent/config/cli-flags) +2. [Configuration files](/consul/docs/agent/config/config-files) When loading configuration, the Consul agent loads the configuration from files and directories in lexical order. For example, configuration file @@ -34,11 +34,11 @@ The Consul agent also supports reloading configuration when it receives the SIGHUP signal. Not all changes are respected, but those that are documented below in the [Reloadable Configuration](#reloadable-configuration) section. The -[reload command](/commands/reload) can also be used to trigger a +[reload command](/consul/commands/reload) can also be used to trigger a configuration reload. You can test the following configuration options by following the -[Get Started](https://developer.hashicorp.com/consul/tutorials/get-started-vms?utm_source=docs) +[Get Started](/consul/tutorials/get-started-vms?utm_source=docs) tutorials to install an agent in a VM. ## Ports Used @@ -46,49 +46,49 @@ tutorials to install an agent in a VM. Consul requires up to 6 different ports to work properly, some on TCP, UDP, or both protocols. -Review the [required ports](/docs/install/ports) table for a list of +Review the [required ports](/consul/docs/install/ports) table for a list of required ports and their default settings. ## Reloadable Configuration Some agent configuration options are reloadable at runtime. -You can run the [`consul reload` command](/commands/reload) to manually reload supported options from configuration files in the configuration directory. +You can run the [`consul reload` command](/consul/commands/reload) to manually reload supported options from configuration files in the configuration directory. To configure the agent to automatically reload configuration files updated on disk, set the [`auto_reload_config` configuration option](/consul/docs/agent/config/config-files#auto_reload_config) parameter to `true`. The following agent configuration options are reloadable at runtime: - ACL Tokens -- [Configuration Entry Bootstrap](/docs/agent/config/config-files#config_entries_bootstrap) +- [Configuration Entry Bootstrap](/consul/docs/agent/config/config-files#config_entries_bootstrap) - Checks -- [Discard Check Output](/docs/agent/config/config-files#discard_check_output) +- [Discard Check Output](/consul/docs/agent/config/config-files#discard_check_output) - HTTP Client Address - Log level -- [Metric Prefix Filter](/docs/agent/config/config-files#telemetry-prefix_filter) -- [Node Metadata](/docs/agent/config/config-files#node_meta) +- [Metric Prefix Filter](/consul/docs/agent/config/config-files#telemetry-prefix_filter) +- [Node Metadata](/consul/docs/agent/config/config-files#node_meta) - Some Raft options (since Consul 1.10.0) - - [`raft_snapshot_threshold`](/docs/agent/config/config-files#_raft_snapshot_threshold) - - [`raft_snapshot_interval`](/docs/agent/config/config-files#_raft_snapshot_interval) - - [`raft_trailing_logs`](/docs/agent/config/config-files#_raft_trailing_logs) + - [`raft_snapshot_threshold`](/consul/docs/agent/config/config-files#_raft_snapshot_threshold) + - [`raft_snapshot_interval`](/consul/docs/agent/config/config-files#_raft_snapshot_interval) + - [`raft_trailing_logs`](/consul/docs/agent/config/config-files#_raft_trailing_logs) - These can be important in certain outage situations so being able to control them without a restart provides a recovery path that doesn't involve downtime. They generally shouldn't be changed otherwise. -- [RPC rate limiting](/docs/agent/config/config-files#limits) -- [HTTP Maximum Connections per Client](/docs/agent/config/config-files#http_max_conns_per_client) +- [RPC rate limiting](/consul/docs/agent/config/config-files#limits) +- [HTTP Maximum Connections per Client](/consul/docs/agent/config/config-files#http_max_conns_per_client) - Services - TLS Configuration - Please be aware that this is currently limited to reload a configuration that is already TLS enabled. You cannot enable or disable TLS only with reloading. - - To avoid a potential security issue, the following TLS configuration parameters do not automatically reload when [-auto-reload-config](/docs/agent/config/cli-flags#_auto_reload_config) is enabled: - - [encrypt_verify_incoming](/docs/agent/config/config-files#encrypt_verify_incoming) - - [verify_incoming](/docs/agent/config/config-files#verify_incoming) - - [verify_incoming_rpc](/docs/agent/config/config-files#verify_incoming_rpc) - - [verify_incoming_https](/docs/agent/config/config-files#verify_incoming_https) - - [verify_outgoing](/docs/agent/config/config-files#verify_outgoing) - - [verify_server_hostname](/docs/agent/config/config-files#verify_server_hostname) - - [ca_file](/docs/agent/config/config-files#ca_file) - - [ca_path](/docs/agent/config/config-files#ca_path) + - To avoid a potential security issue, the following TLS configuration parameters do not automatically reload when [-auto-reload-config](/consul/docs/agent/config/cli-flags#_auto_reload_config) is enabled: + - [encrypt_verify_incoming](/consul/docs/agent/config/config-files#encrypt_verify_incoming) + - [verify_incoming](/consul/docs/agent/config/config-files#verify_incoming) + - [verify_incoming_rpc](/consul/docs/agent/config/config-files#verify_incoming_rpc) + - [verify_incoming_https](/consul/docs/agent/config/config-files#verify_incoming_https) + - [verify_outgoing](/consul/docs/agent/config/config-files#verify_outgoing) + - [verify_server_hostname](/consul/docs/agent/config/config-files#verify_server_hostname) + - [ca_file](/consul/docs/agent/config/config-files#ca_file) + - [ca_path](/consul/docs/agent/config/config-files#ca_path) - If any of those configurations are changed while [-auto-reload-config](/docs/agent/config/cli-flags#_auto_reload_config) is enabled, + If any of those configurations are changed while [-auto-reload-config](/consul/docs/agent/config/cli-flags#_auto_reload_config) is enabled, Consul will issue the following warning, `Static Runtime config has changed and need a manual config reload to be applied`. You must manually issue the `consul reload` command or send a `SIGHUP` to the Consul process to reload the new values. - Watches -- [License](/docs/enterprise/license/overview) +- [License](/consul/docs/enterprise/license/overview) diff --git a/website/content/docs/agent/index.mdx b/website/content/docs/agent/index.mdx index 33e6167044..bab9138e50 100644 --- a/website/content/docs/agent/index.mdx +++ b/website/content/docs/agent/index.mdx @@ -15,7 +15,7 @@ Agents run in either client or server mode. Client nodes are lightweight process They interface with the server nodes for most operations and maintain very little state of their own. Clients run on every node where services are running. -In addition to the core agent operations, server nodes participate in the [consensus quorum](/docs/architecture/consensus). +In addition to the core agent operations, server nodes participate in the [consensus quorum](/consul/docs/architecture/consensus). The quorum is based on the Raft protocol, which provides strong consistency and availability in the case of failure. Server nodes should run on dedicated instances because they are more resource intensive than client nodes. @@ -28,7 +28,7 @@ The following process describes the agent lifecycle within the context of an exi 1. **An agent is started** either manually or through an automated or programmatic process. Newly-started agents are unaware of other nodes in the cluster. 1. **An agent joins a cluster**, which enables the agent to discover agent peers. - Agents join clusters on startup when the [`join`](/commands/join) command is issued or according the [auto-join configuration](/docs/install/cloud-auto-join). + Agents join clusters on startup when the [`join`](/consul/commands/join) command is issued or according the [auto-join configuration](/consul/docs/install/cloud-auto-join). 1. **Information about the agent is gossiped to the entire cluster**. As a result, all nodes will eventually become aware of each other. 1. **Existing servers will begin replicating to the new node** if the agent is a server. @@ -44,7 +44,7 @@ As a result, agent crashes are handled in the same manner is network failures. Once a node is marked as failed, this information is updated in the service catalog. --> **Note:** Updating the catalog is only possible if the servers can still [form a quorum](/docs/architecture/consensus). +-> **Note:** Updating the catalog is only possible if the servers can still [form a quorum](/consul/docs/architecture/consensus). Once the network recovers or a crashed agent restarts, the cluster will repair itself and unmark a node as failed. The health check in the catalog will also be updated to reflect the current state. @@ -68,10 +68,10 @@ Instances of Consul can run in separate VMs or as separate containers. At least one server agent per Consul deployment is required, but three to five server agents are recommended. Refer to the following sections for information about host, port, memory, and other requirements: -- [Server Performance](/docs/install/performance) -- [Required Ports](/docs/install/ports) +- [Server Performance](/consul/docs/install/performance) +- [Required Ports](/consul/docs/install/ports) -The [Datacenter Deploy tutorial](https://learn.hashicorp.com/tutorials/consul/reference-architecture?in=consul/production-deploy#deployment-system-requirements) contains additional information, including licensing configuration, environment variables, and other details. +The [Datacenter Deploy tutorial](/consul/tutorials/production-deploy/reference-architecture#deployment-system-requirements) contains additional information, including licensing configuration, environment variables, and other details. ### Maximum Latency Network requirements @@ -95,13 +95,13 @@ The `-dev` flag is provided for learning purposes only. We strongly advise against using it for production environments. -> **Getting Started Tutorials**: You can test a local agent in a VM by following the -[Get Started tutorials](https://developer.hashicorp.com/consul/tutorials/get-started-vms?utm_source=docs). +[Get Started tutorials](/consul/tutorials/get-started-vms?utm_source=docs). When starting Consul with the `-dev` flag, the only additional information Consul needs to run is the location of a directory for storing agent state data. You can specify the location with the `-data-dir` flag or define the location in an external file and point the file with the `-config-file` flag. You can also point to a directory containing several configuration files with the `-config-dir` flag. -This enables you to logically group configuration settings into separate files. See [Configuring Consul Agents](/docs/agent#configuring-consul-agents) for additional information. +This enables you to logically group configuration settings into separate files. See [Configuring Consul Agents](/consul/docs/agent#configuring-consul-agents) for additional information. The following example starts an agent in dev mode and stores agent state data in the `tmp/consul` directory: @@ -109,12 +109,12 @@ The following example starts an agent in dev mode and stores agent state data in $ consul agent -data-dir=tmp/consul -dev ``` -Agents are highly configurable, which enables you to deploy Consul to any infrastructure. Many of the default options for the `agent` command are suitable for becoming familiar with a local instance of Consul. In practice, however, several additional configuration options must be specified for Consul to function as expected. Refer to [Agent Configuration](/docs/agent/config) topic for a complete list of configuration options. +Agents are highly configurable, which enables you to deploy Consul to any infrastructure. Many of the default options for the `agent` command are suitable for becoming familiar with a local instance of Consul. In practice, however, several additional configuration options must be specified for Consul to function as expected. Refer to [Agent Configuration](/consul/docs/agent/config) topic for a complete list of configuration options. ### Understanding the Agent Startup Output Consul prints several important messages on startup. -The following example shows output from the [`consul agent`](/commands/agent) command: +The following example shows output from the [`consul agent`](/consul/commands/agent) command: ```shell-session $ consul agent -data-dir=/tmp/consul @@ -134,24 +134,24 @@ $ consul agent -data-dir=/tmp/consul - **Node name**: This is a unique name for the agent. By default, this is the hostname of the machine, but you may customize it using the - [`-node`](/docs/agent/config/cli-flags#_node) flag. + [`-node`](/consul/docs/agent/config/cli-flags#_node) flag. - **Datacenter**: This is the datacenter in which the agent is configured to - run. For single-DC configurations, the agent will default to `dc1`, but you can configure which datacenter the agent reports to with the [`-datacenter`](/docs/agent/config/cli-flags#_datacenter) flag. + run. For single-DC configurations, the agent will default to `dc1`, but you can configure which datacenter the agent reports to with the [`-datacenter`](/consul/docs/agent/config/cli-flags#_datacenter) flag. Consul has first-class support for multiple datacenters, but configuring each node to report its datacenter improves agent efficiency. - **Server**: This indicates whether the agent is running in server or client mode. Running an agent in server mode requires additional overhead. This is because they participate in the consensus quorum, store cluster state, and handle queries. A server may also be - in ["bootstrap"](/docs/agent/config/cli-flags#_bootstrap_expect) mode, which enables the server to elect itself as the Raft leader. Multiple servers cannot be in bootstrap mode because it would put the cluster in an inconsistent state. + in ["bootstrap"](/consul/docs/agent/config/cli-flags#_bootstrap_expect) mode, which enables the server to elect itself as the Raft leader. Multiple servers cannot be in bootstrap mode because it would put the cluster in an inconsistent state. - **Client Addr**: This is the address used for client interfaces to the agent. This includes the ports for the HTTP and DNS interfaces. By default, this binds only to localhost. If you change this address or port, you'll have to specify a `-http-addr` whenever you run commands such as - [`consul members`](/commands/members) to indicate how to reach the + [`consul members`](/consul/commands/members) to indicate how to reach the agent. Other applications can also use the HTTP address and port - [to control Consul](/api-docs). + [to control Consul](/consul/api-docs). - **Cluster Addr**: This is the address and set of ports used for communication between Consul agents in a cluster. Not all Consul agents in a cluster have to @@ -186,19 +186,19 @@ The following settings are commonly used in the configuration file (also called | Parameter | Description | Default | | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- | -| `node_name` | String value that specifies a name for the agent node.
See [`-node-id`](/docs/agent/config/cli-flags#_node_id) for details. | Hostname of the machine | -| `server` | Boolean value that determines if the agent runs in server mode.
See [`-server`](/docs/agent/config/cli-flags#_server) for details. | `false` | -| `datacenter` | String value that specifies which datacenter the agent runs in.
See [-datacenter](/docs/agent/config/cli-flags#_datacenter) for details. | `dc1` | -| `data_dir` | String value that specifies a directory for storing agent state data.
See [`-data-dir`](/docs/agent/config/cli-flags#_data_dir) for details. | none | -| `log_level` | String value that specifies the level of logging the agent reports.
See [`-log-level`](/docs/agent/config/cli-flags#_log_level) for details. | `info` | -| `retry_join` | Array of string values that specify one or more agent addresses to join after startup. The agent will continue trying to join the specified agents until it has successfully joined another member.
See [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) for details. | none | -| `addresses` | Block of nested objects that define addresses bound to the agent for internal cluster communication. | `"http": "0.0.0.0"` See the Agent Configuration page for [default address values](/docs/agent/config/config-files#addresses) | -| `ports` | Block of nested objects that define ports bound to agent addresses.
See (link to addresses option) for details. | See the Agent Configuration page for [default port values](/docs/agent/config/config-files#ports) | +| `node_name` | String value that specifies a name for the agent node.
See [`-node-id`](/consul/docs/agent/config/cli-flags#_node_id) for details. | Hostname of the machine | +| `server` | Boolean value that determines if the agent runs in server mode.
See [`-server`](/consul/docs/agent/config/cli-flags#_server) for details. | `false` | +| `datacenter` | String value that specifies which datacenter the agent runs in.
See [-datacenter](/consul/docs/agent/config/cli-flags#_datacenter) for details. | `dc1` | +| `data_dir` | String value that specifies a directory for storing agent state data.
See [`-data-dir`](/consul/docs/agent/config/cli-flags#_data_dir) for details. | none | +| `log_level` | String value that specifies the level of logging the agent reports.
See [`-log-level`](/consul/docs/agent/config/cli-flags#_log_level) for details. | `info` | +| `retry_join` | Array of string values that specify one or more agent addresses to join after startup. The agent will continue trying to join the specified agents until it has successfully joined another member.
See [`-retry-join`](/consul/docs/agent/config/cli-flags#_retry_join) for details. | none | +| `addresses` | Block of nested objects that define addresses bound to the agent for internal cluster communication. | `"http": "0.0.0.0"` See the Agent Configuration page for [default address values](/consul/docs/agent/config/config-files#addresses) | +| `ports` | Block of nested objects that define ports bound to agent addresses.
See (link to addresses option) for details. | See the Agent Configuration page for [default port values](/consul/docs/agent/config/config-files#ports) | ### Server Node in a Service Mesh -The following example configuration is for a server agent named "`consul-server`". The server is [bootstrapped](/docs/agent/config/cli-flags#_bootstrap) and the Consul GUI is enabled. -The reason this server agent is configured for a service mesh is that the `connect` configuration is enabled. Connect is Consul's service mesh component that provides service-to-service connection authorization and encryption using mutual Transport Layer Security (TLS). Applications can use sidecar proxies in a service mesh configuration to establish TLS connections for inbound and outbound connections without being aware of Connect at all. See [Connect](/docs/connect) for details. +The following example configuration is for a server agent named "`consul-server`". The server is [bootstrapped](/consul/docs/agent/config/cli-flags#_bootstrap) and the Consul GUI is enabled. +The reason this server agent is configured for a service mesh is that the `connect` configuration is enabled. Connect is Consul's service mesh component that provides service-to-service connection authorization and encryption using mutual Transport Layer Security (TLS). Applications can use sidecar proxies in a service mesh configuration to establish TLS connections for inbound and outbound connections without being aware of Connect at all. See [Connect](/consul/docs/connect) for details. @@ -246,7 +246,7 @@ connect { ### Server Node with Encryption Enabled The following example shows a server node configured with encryption enabled. -Refer to the [Security](/docs/security) chapter for additional information about how to configure security options for Consul. +Refer to the [Security](/consul/docs/security) chapter for additional information about how to configure security options for Consul. @@ -316,7 +316,7 @@ tls { ### Client Node Registering a Service Using Consul as a central service registry is a common use case. -The following example configuration includes common settings to register a service with a Consul agent and enable health checks (see [Checks](/docs/discovery/checks) to learn more about health checks): +The following example configuration includes common settings to register a service with a Consul agent and enable health checks (see [Checks](/consul/docs/discovery/checks) to learn more about health checks): @@ -375,9 +375,9 @@ service { The following example shows how to configure Consul to listen on multiple interfaces or IP addresses using a [go-sockaddr template]. -The `bind_addr` is used for internal RPC and Serf communication ([read the Agent Configuration for more information](/docs/agent/config/config-files#bind_addr)). +The `bind_addr` is used for internal RPC and Serf communication ([read the Agent Configuration for more information](/consul/docs/agent/config/config-files#bind_addr)). -The `client_addr` configuration specifies IP addresses used for HTTP, HTTPS, DNS and gRPC servers. ([read the Agent Configuration for more information](/docs/agent/config/config-files#client_addr)). +The `client_addr` configuration specifies IP addresses used for HTTP, HTTPS, DNS and gRPC servers. ([read the Agent Configuration for more information](/consul/docs/agent/config/config-files#client_addr)). @@ -441,7 +441,7 @@ cluster that the node has _left_. When a Server is gracefully exited, the server will not be marked as _left_. This is to minimally impact the consensus quorum. Instead, the Server will be marked as _failed_. To remove a server from the cluster, the -[`force-leave`](/commands/force-leave) command is used. Using +[`force-leave`](/consul/commands/force-leave) command is used. Using `force-leave` will put the server instance in a _left_ state so long as the Server agent is not alive. @@ -455,8 +455,8 @@ may not be important for your use case. For example, for a web server and load balancer setup, both result in the same outcome: the web node is removed from the load balancer pool. -The [`skip_leave_on_interrupt`](/docs/agent/config/config-files#skip_leave_on_interrupt) and -[`leave_on_terminate`](/docs/agent/config/config-files#leave_on_terminate) configuration +The [`skip_leave_on_interrupt`](/consul/docs/agent/config/config-files#skip_leave_on_interrupt) and +[`leave_on_terminate`](/consul/docs/agent/config/config-files#leave_on_terminate) configuration options allow you to adjust this behavior. diff --git a/website/content/docs/agent/rpc.mdx b/website/content/docs/agent/rpc.mdx index 1ce908594d..bdff4a05fc 100644 --- a/website/content/docs/agent/rpc.mdx +++ b/website/content/docs/agent/rpc.mdx @@ -8,7 +8,7 @@ description: >- # RPC Protocol ~> The RPC Protocol is deprecated and support was removed in Consul -0.8. Please use the [HTTP API](/api-docs), which has +0.8. Please use the [HTTP API](/consul/api-docs), which has support for all features of the RPC Protocol. The Consul agent provides a complete RPC mechanism that can @@ -18,7 +18,7 @@ used by other applications to easily leverage the power of Consul without directly embedding. It is important to note that the RPC protocol does not support -all the same operations as the [HTTP API](/api-docs). +all the same operations as the [HTTP API](/consul/api-docs). ## Implementation Details diff --git a/website/content/docs/agent/sentinel.mdx b/website/content/docs/agent/sentinel.mdx index fde0d479cb..e7bfbf8eb6 100644 --- a/website/content/docs/agent/sentinel.mdx +++ b/website/content/docs/agent/sentinel.mdx @@ -17,7 +17,7 @@ policies to support full conditional logic and integration with external systems Sentinel policies are applied during writes to the KV Store. -An optional `sentinel` field specifying code and enforcement level can be added to [ACL policy definitions](/docs/security/acl/acl-rules#sentinel-integration) for Consul KV. The following policy ensures that the value written during a KV update must end with "dc1". +An optional `sentinel` field specifying code and enforcement level can be added to [ACL policy definitions](/consul/docs/security/acl/acl-rules#sentinel-integration) for Consul KV. The following policy ensures that the value written during a KV update must end with "dc1". @@ -52,7 +52,7 @@ Consul passes some context as variables into Sentinel, which are available to us | ------------- | -------- | ---------------------- | | `key` | `string` | Key being written | | `value` | `string` | Value being written | -| `flags` | `uint64` | [Flags](/api-docs/kv#flags) | +| `flags` | `uint64` | [Flags](/consul/api-docs/kv#flags) | ## Sentinel Examples diff --git a/website/content/docs/agent/telemetry.mdx b/website/content/docs/agent/telemetry.mdx index 1e576d3d35..9859a14394 100644 --- a/website/content/docs/agent/telemetry.mdx +++ b/website/content/docs/agent/telemetry.mdx @@ -25,16 +25,16 @@ it will dump the current telemetry information to the agent's `stderr`. This telemetry information can be used for debugging or otherwise getting a better view of what Consul is doing. Review the [Monitoring and -Metrics tutorial](https://learn.hashicorp.com/tutorials/consul/monitor-datacenter-health?utm_source=docs) to learn how collect and interpret Consul data. +Metrics tutorial](/consul/tutorials/day-2-operations/monitor-datacenter-health?utm_source=docs) to learn how collect and interpret Consul data. -Additionally, if the [`telemetry` configuration options](/docs/agent/config/config-files#telemetry) +Additionally, if the [`telemetry` configuration options](/consul/docs/agent/config/config-files#telemetry) are provided, the telemetry information will be streamed to a [statsite](http://github.com/armon/statsite) or [statsd](http://github.com/etsy/statsd) server where it can be aggregated and flushed to Graphite or any other metrics store. -For a configuration example for Telegraf, review the [Monitoring with Telegraf tutorial](https://learn.hashicorp.com/tutorials/consul/monitor-health-telegraf?utm_source=docs). +For a configuration example for Telegraf, review the [Monitoring with Telegraf tutorial](/consul/tutorials/day-2-operations/monitor-health-telegraf?utm_source=docs). This -information can also be viewed with the [metrics endpoint](/api-docs/agent#view-metrics) in JSON +information can also be viewed with the [metrics endpoint](/consul/api-docs/agent#view-metrics) in JSON format or using [Prometheus](https://prometheus.io/) format. @@ -139,7 +139,7 @@ you will need to apply a function such as InfluxDB's [`non_negative_difference() | Metric Name | Description | Unit | Type | | :--------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------- | :------ | | `consul.client.rpc` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server | requests | counter | -| `consul.client.rpc.exceeded` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server gets rate limited by that agent's [`limits`](/docs/agent/config/config-files#limits) configuration. | requests | counter | +| `consul.client.rpc.exceeded` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server gets rate limited by that agent's [`limits`](/consul/docs/agent/config/config-files#limits) configuration. | requests | counter | | `consul.client.rpc.failed` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server and fails. | requests | counter | **Why they're important:** These measurements indicate the current load created from a Consul agent, including when the load becomes high enough to be rate limited. A high RPC count, especially from `consul.client.rpcexceeded` meaning that the requests are being rate-limited, could imply a misconfigured Consul agent. @@ -193,7 +193,7 @@ Under these conditions, a follower after a restart may be unable to catch up on replication and become a voter again since it takes longer to restore from disk or the leader than the leader takes to write a new snapshot and truncate its logs. Servers retain -[`raft_trailing_logs`](/docs/agent/config/config-files#raft_trailing_logs) (default +[`raft_trailing_logs`](/consul/docs/agent/config/config-files#raft_trailing_logs) (default `10240`) log entries even if their snapshot was more recent. On a leader processing 500 commits/second, that is only about 20 seconds worth of logs. Assuming the leader is able to write out a snapshot and truncate the logs in @@ -218,7 +218,7 @@ repeatedly as well as reduce the fault tolerance and serving capacity of the cluster. Since Consul 1.5.3 -[`raft_trailing_logs`](/docs/agent/config/config-files#raft_trailing_logs) has been +[`raft_trailing_logs`](/consul/docs/agent/config/config-files#raft_trailing_logs) has been configurable. Increasing it allows the leader to retain more logs and give followers more time to restore and catch up. The tradeoff is potentially slower appends which eventually might affect write throughput and latency @@ -229,7 +229,7 @@ mean loosing cluster availability and needing to recover the cluster from a loss of quorum. Since Consul 1.10.0 -[`raft_trailing_logs`](/docs/agent/config/config-files#raft_trailing_logs) is now +[`raft_trailing_logs`](/consul/docs/agent/config/config-files#raft_trailing_logs) is now reloadable with `consul reload` or `SIGHUP` allowing operators to increase this without the leader restarting or loosing leadership allowing the cluster to be recovered gracefully. @@ -294,7 +294,7 @@ This metric should be monitored to ensure that the license doesn't expire to pre | Metric Name | Description | Unit | Type | | :-------------------------------- | :--------------------------------------------------------------- | :---- | :---- | -| `consul.raft.boltdb.freelistBytes` | Represents the number of bytes necessary to encode the freelist metadata. When [`raft_boltdb.NoFreelistSync`](/docs/agent/config/config-files#NoFreelistSync) is set to `false` these metadata bytes must also be written to disk for each committed log. | bytes | gauge | +| `consul.raft.boltdb.freelistBytes` | Represents the number of bytes necessary to encode the freelist metadata. When [`raft_boltdb.NoFreelistSync`](/consul/docs/agent/config/config-files#NoFreelistSync) is set to `false` these metadata bytes must also be written to disk for each committed log. | bytes | gauge | | `consul.raft.boltdb.logsPerBatch` | Measures the number of logs being written per batch to the db. | logs | sample | | `consul.raft.boltdb.storeLogs` | Measures the amount of time spent writing logs to the db. | ms | timer | | `consul.raft.boltdb.writeCapacity` | Theoretical write capacity in terms of the number of logs that can be written per second. Each sample outputs what the capacity would be if future batched log write operations were similar to this one. This similarity encompasses 4 things: batch size, byte size, disk performance and boltdb performance. While none of these will be static and its highly likely individual samples of this metric will vary, aggregating this metric over a larger time window should provide a decent picture into how this BoltDB store can perform | logs/second | sample | @@ -337,7 +337,7 @@ indicator of an actual issue, this metric can be used to diagnose why the `consu is high. If Bolt DB log storage performance becomes an issue and is caused by free list management then setting -[`raft_boltdb.NoFreelistSync`](/docs/agent/config/config-files#NoFreelistSync) to `true` in the server's configuration +[`raft_boltdb.NoFreelistSync`](/consul/docs/agent/config/config-files#NoFreelistSync) to `true` in the server's configuration may help to reduce disk IO and log storage operation times. Disabling free list syncing will however increase the startup time for a server as it must scan the raft.db file for free space instead of loading the already populated free list structure. @@ -353,7 +353,7 @@ This is a full list of metrics emitted by Consul. | `consul.acl.blocked.{check,node,service}.registration` | Increments whenever a registration fails for an entity (check, node or service) is blocked by an ACL. | requests | counter | | `consul.api.http` | This samples how long it takes to service the given HTTP request for the given verb and path. Includes labels for `path` and `method`. `path` does not include details like service or key names, for these an underscore will be present as a placeholder (eg. path=`v1.kv._`) | ms | timer | | `consul.client.rpc` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server. This gives a measure of how much a given agent is loading the Consul servers. Currently, this is only generated by agents in client mode, not Consul servers. | requests | counter | -| `consul.client.rpc.exceeded` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server gets rate limited by that agent's [`limits`](/docs/agent/config/config-files#limits) configuration. This gives an indication that there's an abusive application making too many requests on the agent, or that the rate limit needs to be increased. Currently, this only applies to agents in client mode, not Consul servers. | rejected requests | counter | +| `consul.client.rpc.exceeded` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server gets rate limited by that agent's [`limits`](/consul/docs/agent/config/config-files#limits) configuration. This gives an indication that there's an abusive application making too many requests on the agent, or that the rate limit needs to be increased. Currently, this only applies to agents in client mode, not Consul servers. | rejected requests | counter | | `consul.client.rpc.failed` | Increments whenever a Consul agent in client mode makes an RPC request to a Consul server and fails. | requests | counter | | `consul.client.api.catalog_register.` | Increments whenever a Consul agent receives a catalog register request. | requests | counter | | `consul.client.api.success.catalog_register.` | Increments whenever a Consul agent successfully responds to a catalog register request. | requests | counter | @@ -392,7 +392,7 @@ This is a full list of metrics emitted by Consul. | `consul.state.service_instances` | Measures the current number of unique service instances registered with Consul. It is only emitted by Consul servers. Added in v1.9.0. | number of objects | gauge | | `consul.state.kv_entries` | Measures the current number of entries in the Consul KV store. It is only emitted by Consul servers. Added in v1.10.3. | number of objects | gauge | | `consul.state.connect_instances` | Measures the current number of unique connect service instances registered with Consul labeled by Kind (e.g. connect-proxy, connect-native, etc). Added in v1.10.4 | number of objects | gauge | -| `consul.state.config_entries` | Measures the current number of configuration entries registered with Consul labeled by Kind (e.g. service-defaults, proxy-defaults, etc). See [Configuration Entries](/docs/connect/config-entries) for more information. Added in v1.10.4 | number of objects | gauge | +| `consul.state.config_entries` | Measures the current number of configuration entries registered with Consul labeled by Kind (e.g. service-defaults, proxy-defaults, etc). See [Configuration Entries](/consul/docs/connect/config-entries) for more information. Added in v1.10.4 | number of objects | gauge | | `consul.members.clients` | Measures the current number of client agents registered with Consul. It is only emitted by Consul servers. Added in v1.9.6. | number of clients | gauge | | `consul.members.servers` | Measures the current number of server agents registered with Consul. It is only emitted by Consul servers. Added in v1.9.6. | number of servers | gauge | | `consul.dns.stale_queries` | Increments when an agent serves a query within the allowed stale threshold. | queries | counter | @@ -418,7 +418,7 @@ These metrics are used to monitor the health of the Consul servers. | `consul.raft.applied_index` | Represents the raft applied index. | index | gauge | | `consul.raft.apply` | Counts the number of Raft transactions occurring over the interval, which is a general indicator of the write load on the Consul servers. | raft transactions / interval | counter | | `consul.raft.barrier` | Counts the number of times the agent has started the barrier i.e the number of times it has issued a blocking call, to ensure that the agent has all the pending operations that were queued, to be applied to the agent's FSM. | blocks / interval | counter | -| `consul.raft.boltdb.freelistBytes` | Represents the number of bytes necessary to encode the freelist metadata. When [`raft_boltdb.NoFreelistSync`](/docs/agent/config/config-files#NoFreelistSync) is set to `false` these metadata bytes must also be written to disk for each committed log. | bytes | gauge | +| `consul.raft.boltdb.freelistBytes` | Represents the number of bytes necessary to encode the freelist metadata. When [`raft_boltdb.NoFreelistSync`](/consul/docs/agent/config/config-files#NoFreelistSync) is set to `false` these metadata bytes must also be written to disk for each committed log. | bytes | gauge | | `consul.raft.boltdb.freePageBytes` | Represents the number of bytes of free space within the raft.db file. | bytes | gauge | | `consul.raft.boltdb.getLog` | Measures the amount of time spent reading logs from the db. | ms | timer | | `consul.raft.boltdb.logBatchSize` | Measures the total size in bytes of logs being written to the db in a single batch. | bytes | sample | @@ -452,7 +452,7 @@ These metrics are used to monitor the health of the Consul servers. | `consul.raft.last_index` | Represents the raft applied index. | index | gauge | | `consul.raft.leader.dispatchLog` | Measures the time it takes for the leader to write log entries to disk. | ms | timer | | `consul.raft.leader.dispatchNumLogs` | Measures the number of logs committed to disk in a batch. | logs | gauge | -| `consul.raft.leader.lastContact` | Measures the time since the leader was last able to contact the follower nodes when checking its leader lease. It can be used as a measure for how stable the Raft timing is and how close the leader is to timing out its lease.The lease timeout is 500 ms times the [`raft_multiplier` configuration](/docs/agent/config/config-files#raft_multiplier), so this telemetry value should not be getting close to that configured value, otherwise the Raft timing is marginal and might need to be tuned, or more powerful servers might be needed. See the [Server Performance](/docs/install/performance) guide for more details. | ms | timer | +| `consul.raft.leader.lastContact` | Measures the time since the leader was last able to contact the follower nodes when checking its leader lease. It can be used as a measure for how stable the Raft timing is and how close the leader is to timing out its lease.The lease timeout is 500 ms times the [`raft_multiplier` configuration](/consul/docs/agent/config/config-files#raft_multiplier), so this telemetry value should not be getting close to that configured value, otherwise the Raft timing is marginal and might need to be tuned, or more powerful servers might be needed. See the [Server Performance](/consul/docs/install/performance) guide for more details. | ms | timer | | `consul.raft.leader.oldestLogAge` | The number of milliseconds since the _oldest_ log in the leader's log store was written. This can be important for replication health where write rate is high and the snapshot is large as followers may be unable to recover from a restart if restoring takes longer than the minimum value for the current leader. Compare this with `consul.raft.fsm.lastRestoreDuration` and `consul.raft.rpc.installSnapshot` to monitor. In normal usage this gauge value will grow linearly over time until a snapshot completes on the leader and the log is truncated. Note: this metric won't be emitted until the leader writes a snapshot. After an upgrade to Consul 1.10.0 it won't be emitted until the oldest log was written after the upgrade. | ms | gauge | | `consul.raft.replication.heartbeat` | Measures the time taken to invoke appendEntries on a peer, so that it doesn't timeout on a periodic basis. | ms | timer | | `consul.raft.replication.appendEntries` | Measures the time it takes to replicate log entries to followers. This is a general indicator of the load pressure on the Consul servers, as well as the performance of the communication between the servers. | ms | timer | @@ -601,7 +601,7 @@ Here is a Prometheus style example of an RPC metric and its labels: -Any metric in this section can be turned off with the [`prefix_filter`](/docs/agent/config/config-files#telemetry-prefix_filter). +Any metric in this section can be turned off with the [`prefix_filter`](/consul/docs/agent/config/config-files#telemetry-prefix_filter). ## Cluster Health @@ -617,7 +617,7 @@ are allowed for . | `consul.memberlist.degraded.timeout` | Counts the number of times an agent was marked as a dead node, whilst not getting enough confirmations from a randomly selected list of agent nodes in an agent's membership. | occurrence / interval | counter | | `consul.memberlist.msg.dead` | Counts the number of times an agent has marked another agent to be a dead node. | messages / interval | counter | | `consul.memberlist.health.score` | Describes a node's perception of its own health based on how well it is meeting the soft real-time requirements of the protocol. This metric ranges from 0 to 8, where 0 indicates "totally healthy". This health score is used to scale the time between outgoing probes, and higher scores translate into longer probing intervals. For more details see section IV of the Lifeguard paper: https://arxiv.org/pdf/1707.00788.pdf | score | gauge | -| `consul.memberlist.msg.suspect` | Increments when an agent suspects another as failed when executing random probes as part of the gossip protocol. These can be an indicator of overloaded agents, network problems, or configuration errors where agents can not connect to each other on the [required ports](/docs/agent/config/config-files#ports). | suspect messages received / interval | counter | +| `consul.memberlist.msg.suspect` | Increments when an agent suspects another as failed when executing random probes as part of the gossip protocol. These can be an indicator of overloaded agents, network problems, or configuration errors where agents can not connect to each other on the [required ports](/consul/docs/agent/config/config-files#ports). | suspect messages received / interval | counter | | `consul.memberlist.tcp.accept` | Counts the number of times an agent has accepted an incoming TCP stream connection. | connections accepted / interval | counter | | `consul.memberlist.udp.sent/received` | Measures the total number of bytes sent/received by an agent through the UDP protocol. | bytes sent or bytes received / interval | counter | | `consul.memberlist.tcp.connect` | Counts the number of times an agent has initiated a push/pull sync with an other agent. | push/pull initiated / interval | counter | @@ -632,11 +632,11 @@ are allowed for . | `consul.memberlist.queue.broadcasts` | Measures the number of messages waiting to be broadcast to other gossip participants. | messages | sample | | `consul.memberlist.size.local` | Measures the size in bytes of the memberlist before it is sent to another gossip recipient. | bytes | gauge | | `consul.memberlist.size.remote` | Measures the size in bytes of incoming memberlists from other gossip participants. | bytes | gauge | -| `consul.serf.member.failed` | Increments when an agent is marked dead. This can be an indicator of overloaded agents, network problems, or configuration errors where agents cannot connect to each other on the [required ports](/docs/agent/config/config-files#ports). | failures / interval | counter | -| `consul.serf.member.flap` | Available in Consul 0.7 and later, this increments when an agent is marked dead and then recovers within a short time period. This can be an indicator of overloaded agents, network problems, or configuration errors where agents cannot connect to each other on the [required ports](/docs/agent/config/config-files#ports). | flaps / interval | counter | +| `consul.serf.member.failed` | Increments when an agent is marked dead. This can be an indicator of overloaded agents, network problems, or configuration errors where agents cannot connect to each other on the [required ports](/consul/docs/agent/config/config-files#ports). | failures / interval | counter | +| `consul.serf.member.flap` | Available in Consul 0.7 and later, this increments when an agent is marked dead and then recovers within a short time period. This can be an indicator of overloaded agents, network problems, or configuration errors where agents cannot connect to each other on the [required ports](/consul/docs/agent/config/config-files#ports). | flaps / interval | counter | | `consul.serf.member.join` | Increments when an agent joins the cluster. If an agent flapped or failed this counter also increments when it re-joins. | joins / interval | counter | | `consul.serf.member.left` | Increments when an agent leaves the cluster. | leaves / interval | counter | -| `consul.serf.events` | Increments when an agent processes an [event](/commands/event). Consul uses events internally so there may be additional events showing in telemetry. There are also a per-event counters emitted as `consul.serf.events.`. | events / interval | counter | +| `consul.serf.events` | Increments when an agent processes an [event](/consul/commands/event). Consul uses events internally so there may be additional events showing in telemetry. There are also a per-event counters emitted as `consul.serf.events.`. | events / interval | counter | | `consul.serf.events.` | Breakdown of `consul.serf.events` by type of event. | events / interval | counter | | `consul.serf.msgs.sent` | This metric is sample of the number of bytes of messages broadcast to the cluster. In a given time interval, the sum of this metric is the total number of bytes sent and the count is the number of messages sent. | message bytes / interval | counter | | `consul.autopilot.failure_tolerance` | Tracks the number of voting servers that the cluster can lose while continuing to function. | servers | gauge | @@ -700,11 +700,11 @@ agent. The table below describes the additional metrics exported by the proxy. **Requirements:** - Consul 1.13.0+ -[Cluster peering](/docs/connect/cluster-peering) refers to Consul clusters that communicate through a peer connection, as opposed to a federated connection. Consul collects metrics that describe the number of services exported to a peered cluster. Peering metrics are only emitted by the leader server. These metrics are emitted every 9 seconds. +[Cluster peering](/consul/docs/connect/cluster-peering) refers to Consul clusters that communicate through a peer connection, as opposed to a federated connection. Consul collects metrics that describe the number of services exported to a peered cluster. Peering metrics are only emitted by the leader server. These metrics are emitted every 9 seconds. | Metric | Description | Unit | Type | | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | ------- | -| `consul.peering.exported_services` | Counts the number of services exported with [exported service configuration entries](/docs/connect/config-entries/exported-services) to a peer cluster. | count | gauge | +| `consul.peering.exported_services` | Counts the number of services exported with [exported service configuration entries](/consul/docs/connect/config-entries/exported-services) to a peer cluster. | count | gauge | | `consul.peering.healthy` | Tracks the health of a peering connection as reported by the server. If Consul detects errors while sending or receiving from a peer which do not recover within a reasonable time, this metric returns 0. Healthy connections return 1. | health | gauge | ### Labels diff --git a/website/content/docs/api-gateway/configuration/gateway.mdx b/website/content/docs/api-gateway/configuration/gateway.mdx index 5186a940b2..9d9b87b3b7 100644 --- a/website/content/docs/api-gateway/configuration/gateway.mdx +++ b/website/content/docs/api-gateway/configuration/gateway.mdx @@ -13,7 +13,7 @@ This topic provides full details about the `Gateway` resource. A `Gateway` is an instance of network infrastructure that determines how service traffic should be handled. A `Gateway` contains one or more [`listeners`](#listeners) that bind to a set of IP addresses. An `HTTPRoute` or `TCPRoute` can then attach to a gateway listener to direct traffic from the gateway to a service. -Gateway instances derive their configurations from the [`GatewayClass`](/docs/api-gateway/configuration/gatewayclass) resource, which acts as a template for individual `Gateway` deployments. Refer to [GatewayClass](/docs/api-gateway/configuration/gatewayclass) for additional information. +Gateway instances derive their configurations from the [`GatewayClass`](/consul/docs/api-gateway/configuration/gatewayclass) resource, which acts as a template for individual `Gateway` deployments. Refer to [GatewayClass](/consul/docs/api-gateway/configuration/gatewayclass) for additional information. Specify the following parameters to declare a `Gateway`: @@ -58,7 +58,7 @@ The following outline shows how to format the configurations in the `Gateway` ob This topic provides details about the configuration parameters. ### gatewayClassName -Specifies the name of the [`GatewayClass`](/docs/api-gateway/configuration/gatewayclass) resource used for the `Gateway` instance. Unless you are using a custom [GatewayClass](/docs/api-gateway/configuration/gatewayclass), this value should be set to `consul-api-gateway`. +Specifies the name of the [`GatewayClass`](/consul/docs/api-gateway/configuration/gatewayclass) resource used for the `Gateway` instance. Unless you are using a custom [GatewayClass](/consul/docs/api-gateway/configuration/gatewayclass), this value should be set to `consul-api-gateway`. * Type: string * Required: required diff --git a/website/content/docs/api-gateway/configuration/gatewayclass.mdx b/website/content/docs/api-gateway/configuration/gatewayclass.mdx index 152926be83..fa8fab2d2c 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclass.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclass.mdx @@ -15,7 +15,7 @@ The `GatewayClass` specification includes the name of the controller (`controlle When gateways are created from a `GatewayClass`, they use the parameters specified in the `GatewayClass` at the time of instantiation. -The `GatewayClass` resource is a generic Kubernetes gateway object. For configuration specific to Consul API Gateway, see [GatewayClassConfig](/docs/api-gateway/configuration/gatewayclassconfig). +The `GatewayClass` resource is a generic Kubernetes gateway object. For configuration specific to Consul API Gateway, see [GatewayClassConfig](/consul/docs/api-gateway/configuration/gatewayclassconfig). ## Configuration model The following outline shows how to format the configurations in the `GatewayClass` object. Click on a property name to view details about the configuration. diff --git a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx index 8f83a6cd89..ea3357dece 100644 --- a/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx +++ b/website/content/docs/api-gateway/configuration/gatewayclassconfig.mdx @@ -69,7 +69,7 @@ Set to `true` to enable deployments to run with managed service accounts created * Default: `false` ### consul.authentication.method -Specifies the [Consul auth method](/docs/security/acl/auth-methods) used for initial authentication by Consul API Gateway. +Specifies the [Consul auth method](/consul/docs/security/acl/auth-methods) used for initial authentication by Consul API Gateway. * Type: string * Required: optional diff --git a/website/content/docs/api-gateway/configuration/index.mdx b/website/content/docs/api-gateway/configuration/index.mdx index aa9b571d23..b2d0b19a52 100644 --- a/website/content/docs/api-gateway/configuration/index.mdx +++ b/website/content/docs/api-gateway/configuration/index.mdx @@ -9,15 +9,15 @@ description: >- This topic provides an overview of the configuration items that enable Consul API Gateway to manage traffic into your Consul service mesh. -- [Gateway](/docs/api-gateway/configuration/gateway) defines the main infrastructure resource that links API gateway components. It specifies the name of the `GatewayClass` and one or more [listeners](/docs/api-gateway/configuration/gateway#listeners), which specify the logical endpoints bound to the gateway's addresses. -- [GatewayClass](/docs/api-gateway/configuration/gatewayclass) defines a class of gateway resources that you can use as a template for creating gateways. -- [GatewayClassConfig](/docs/api-gateway/configuration/gatewayclassconfig) describes additional Consul API Gateway-related configuration parameters for the GatewayClass resource. -- [Routes](/docs/api-gateway/configuration/routes) specifies the path from the gateway to the backend service(s) client to the listener. +- [Gateway](/consul/docs/api-gateway/configuration/gateway) defines the main infrastructure resource that links API gateway components. It specifies the name of the `GatewayClass` and one or more [listeners](/consul/docs/api-gateway/configuration/gateway#listeners), which specify the logical endpoints bound to the gateway's addresses. +- [GatewayClass](/consul/docs/api-gateway/configuration/gatewayclass) defines a class of gateway resources that you can use as a template for creating gateways. +- [GatewayClassConfig](/consul/docs/api-gateway/configuration/gatewayclassconfig) describes additional Consul API Gateway-related configuration parameters for the GatewayClass resource. +- [Routes](/consul/docs/api-gateway/configuration/routes) specifies the path from the gateway to the backend service(s) client to the listener. -You can create a basic Gateway object using the default [`gatewayClassName`](/docs/api-gateway/configuration/gateway#gatewayclassname) (`consul-api-gateway`). If you want to create custom Gateways suitable for your environment, complete the following steps: +You can create a basic Gateway object using the default [`gatewayClassName`](/consul/docs/api-gateway/configuration/gateway#gatewayclassname) (`consul-api-gateway`). If you want to create custom Gateways suitable for your environment, complete the following steps: -1. Define a [GatewayClassConfig](/docs/api-gateway/configuration/gatewayclassconfig) that contains your custom configurations. -1. Define a [GatewayClass](/docs/api-gateway/configuration/gatewayclass) and configure the [`parametersRef.name`](/docs/api-gateway/configuration/gatewayclass#parametersref-name) to reference the name of your [GatewayClassConfig](/docs/api-gateway/configuration/gatewayclassconfig). -1. Define a [Gateway](/docs/api-gateway/configuration/gateway) and configure the [`gatewayClassName`](/docs/api-gateway/configuration/gateway#gatewayclassname) to reference the name of your [GatewayClass](/docs/api-gateway/configuration/gatewayclass). +1. Define a [GatewayClassConfig](/consul/docs/api-gateway/configuration/gatewayclassconfig) that contains your custom configurations. +1. Define a [GatewayClass](/consul/docs/api-gateway/configuration/gatewayclass) and configure the [`parametersRef.name`](/consul/docs/api-gateway/configuration/gatewayclass#parametersref-name) to reference the name of your [GatewayClassConfig](/consul/docs/api-gateway/configuration/gatewayclassconfig). +1. Define a [Gateway](/consul/docs/api-gateway/configuration/gateway) and configure the [`gatewayClassName`](/consul/docs/api-gateway/configuration/gateway#gatewayclassname) to reference the name of your [GatewayClass](/consul/docs/api-gateway/configuration/gatewayclass). diff --git a/website/content/docs/api-gateway/configuration/meshservice.mdx b/website/content/docs/api-gateway/configuration/meshservice.mdx index 8b13b2dd0b..b5ac8b2b80 100644 --- a/website/content/docs/api-gateway/configuration/meshservice.mdx +++ b/website/content/docs/api-gateway/configuration/meshservice.mdx @@ -36,7 +36,7 @@ Specifies the name of the service in the Consul service mesh to send traffic to. ### peer Specifies the name of the peered Consul cluster that exported the service. If not specified, Consul defaults to the local datacenter. -You must apply a [`ServiceResolver`](/docs/connect/config-entries/service-resolver) for the referenced service. The `ServiceResolver` configuration entry enables Consul to resolve routes to upstream service instances. +You must apply a [`ServiceResolver`](/consul/docs/connect/config-entries/service-resolver) for the referenced service. The `ServiceResolver` configuration entry enables Consul to resolve routes to upstream service instances. - Type: string - Required: optional diff --git a/website/content/docs/api-gateway/configuration/routes.mdx b/website/content/docs/api-gateway/configuration/routes.mdx index 1b44a8ccef..4702a36083 100644 --- a/website/content/docs/api-gateway/configuration/routes.mdx +++ b/website/content/docs/api-gateway/configuration/routes.mdx @@ -119,7 +119,7 @@ This field specifies backend services that the `Route` references. The following | Parameter | Description | Type | Required | | --- | --- | --- | --- | | `group` | Specifies the Kubernetes API Group of the referenced backend. You can specify the following values:
  • `""`: Specifies the core Kubernetes API group. This value must be used when `kind` is set to `Service`. This is the default value if unspecified.
  • `api-gateway.consul.hashicorp.com`: This value must be used when `kind` is set to `MeshService`.
| String | Optional | -| `kind` | Specifies the Kubernetes Kind of the referenced backend. You can specify the following values:
  • `Service` (default): Indicates that the `backendRef` references a Service in the Kubernetes cluster.
  • `MeshService`: Indicates that the `backendRef` references a service in the Consul mesh. Refer to the `MeshService` [documentation](/docs/api-gateway/configuration/meshservice) for additional information.
| String | Optional | +| `kind` | Specifies the Kubernetes Kind of the referenced backend. You can specify the following values:
  • `Service` (default): Indicates that the `backendRef` references a Service in the Kubernetes cluster.
  • `MeshService`: Indicates that the `backendRef` references a service in the Consul mesh. Refer to the `MeshService` [documentation](/consul/docs/api-gateway/configuration/meshservice) for additional information.
| String | Optional | | `name` | Specifies the name of the Kubernetes Service or Consul mesh service resource. | String | Required | | `namespace` | Specifies the Kubernetes namespace containing the Kubernetes Service or Consul mesh service resource. You must specify a value if the Service or Consul mesh service is defined in a different namespace from the `Route`. Defaults to the namespace of the `Route`.
To create a route for a `backendRef` in a different namespace, you must also create a [ReferenceGrant](https://gateway-api.sigs.k8s.io/v1alpha2/references/spec/#gateway.networking.k8s.io/v1alpha2.ReferenceGrant). Refer to the [example route](#example-cross-namespace-backendref) configured to reference across namespaces. | String | Optional | | `port` | Specifies the port number for accessing the Kubernetes or Consul service. | Integer | Required | @@ -168,7 +168,7 @@ The following example creates a route named `example-route` in namespace `gatewa ### rules.filters -The `filters` block defines steps for processing requests. You can configure filters to modify the properties of matching incoming requests and enable Consul API Gateway features, such as rewriting path prefixes (refer to [Reroute HTTP requests](/docs/api-gateway/usage#reroute-http-requests) for additional information). +The `filters` block defines steps for processing requests. You can configure filters to modify the properties of matching incoming requests and enable Consul API Gateway features, such as rewriting path prefixes (refer to [Reroute HTTP requests](/consul/docs/api-gateway/usage#reroute-http-requests) for additional information). * Type: Array of objects * Required: Optional @@ -203,7 +203,7 @@ Specifies rules for rewriting the URL of incoming requests when `rules.filters.t ### rules.filters.urlRewrite.path -Specifies a list of objects that determine how Consul API Gateway rewrites URL paths (refer to [Reroute HTTP requests](/docs/api-gateway/usage#reroute-http-requests) for additional information). +Specifies a list of objects that determine how Consul API Gateway rewrites URL paths (refer to [Reroute HTTP requests](/consul/docs/api-gateway/usage#reroute-http-requests) for additional information). The following table describes the parameters for `path`: diff --git a/website/content/docs/api-gateway/index.mdx b/website/content/docs/api-gateway/index.mdx index a58cfd77bf..1bdc0bfce9 100644 --- a/website/content/docs/api-gateway/index.mdx +++ b/website/content/docs/api-gateway/index.mdx @@ -42,4 +42,4 @@ are used, see the [documentation in our GitHub repo](https://github.com/hashicor ## Additional Resources -You can learn more about using Consul API Gateway by completing the [Consul API Gateway tutorial](https://learn.hashicorp.com/tutorials/consul/kubernetes-api-gateway). +You can learn more about using Consul API Gateway by completing the [Consul API Gateway tutorial](/consul/tutorials/kubernetes/kubernetes-api-gateway). diff --git a/website/content/docs/api-gateway/install.mdx b/website/content/docs/api-gateway/install.mdx index ecf25f52da..504b2be477 100644 --- a/website/content/docs/api-gateway/install.mdx +++ b/website/content/docs/api-gateway/install.mdx @@ -27,7 +27,7 @@ Ensure that the environment you are deploying Consul API Gateway in meets the re $ kubectl apply --kustomize="github.com/hashicorp/consul-api-gateway/config/crd?ref=v$VERSION" ``` -1. Create a `values.yaml` file for your Consul API Gateway deployment by copying the following content and running it in the environment where you set the `VERSION` environment variable. The Consul Helm chart uses this `values.yaml` file to deploy the API Gateway. Available versions of the [Consul](https://hub.docker.com/r/hashicorp/consul/tags) and [Consul API Gateway](https://hub.docker.com/r/hashicorp/consul-api-gateway/tags) Docker images can be found on DockerHub, with additional context on version compatibility published in [GitHub releases](https://github.com/hashicorp/consul-api-gateway/releases). For more options to configure your Consul API Gateway deployment through the Helm chart, refer to [Helm Chart Configuration - apiGateway](https://www.consul.io/docs/k8s/helm#apigateway). +1. Create a `values.yaml` file for your Consul API Gateway deployment by copying the following content and running it in the environment where you set the `VERSION` environment variable. The Consul Helm chart uses this `values.yaml` file to deploy the API Gateway. Available versions of the [Consul](https://hub.docker.com/r/hashicorp/consul/tags) and [Consul API Gateway](https://hub.docker.com/r/hashicorp/consul-api-gateway/tags) Docker images can be found on DockerHub, with additional context on version compatibility published in [GitHub releases](https://github.com/hashicorp/consul-api-gateway/releases). For more options to configure your Consul API Gateway deployment through the Helm chart, refer to [Helm Chart Configuration - apiGateway](/consul/docs/k8s/helm#apigateway). diff --git a/website/content/docs/api-gateway/tech-specs.mdx b/website/content/docs/api-gateway/tech-specs.mdx index b90706c3f0..9695eb0126 100644 --- a/website/content/docs/api-gateway/tech-specs.mdx +++ b/website/content/docs/api-gateway/tech-specs.mdx @@ -22,7 +22,7 @@ Your datacenter must meet the following requirements prior to configuring the Co - Consul 1.11.2+ - HashiCorp Consul Helm chart 0.47.1+ - Consul Service Mesh must be deployed on the Kubernetes cluster that API Gateway is deployed on. -- Envoy: Envoy proxy support is determined by the Consul version deployed. Refer to [Envoy Integration](/docs/connect/proxies/envoy) for details. +- Envoy: Envoy proxy support is determined by the Consul version deployed. Refer to [Envoy Integration](/consul/docs/connect/proxies/envoy) for details. ### TCP Port Requirements @@ -47,7 +47,7 @@ The following table lists API Gateway limitations related to specific Consul fea | Consul Feature | Limitation | | -------------- | ---------- | -| [Admin partitions](/docs/enterprise/admin-partitions) | You can deploy Consul API Gateway into the `default` admin partition only. You can route to services in other `default` admin partitions through peered connections. Refer to [Route Traffic to Peered Services](/consul/docs/api-gateway/usage/route-to-peered-services) for additional information. | +| [Admin partitions](/consul/docs/enterprise/admin-partitions) | You can deploy Consul API Gateway into the `default` admin partition only. You can route to services in other `default` admin partitions through peered connections. Refer to [Route Traffic to Peered Services](/consul/docs/api-gateway/usage/route-to-peered-services) for additional information. | | Routing between datacenters | If you are connecting multiple Consul datacenters to create a federated network, you can route to services in other datacenters through peered connections. Refer to [Route Traffic to Peered Services](/consul/docs/api-gateway/usage/route-to-peered-services) for additional information. | ## Deployment Environments diff --git a/website/content/docs/api-gateway/usage/errors.mdx b/website/content/docs/api-gateway/usage/errors.mdx index 779f273442..49a9a9a836 100644 --- a/website/content/docs/api-gateway/usage/errors.mdx +++ b/website/content/docs/api-gateway/usage/errors.mdx @@ -9,8 +9,8 @@ description: >- This topic provides information about potential error messages associated with Consul API Gateway. If you receive an error message that does not appear in this section, refer to the following resources: -- [Common Consul errors](/docs/troubleshoot/common-errors#common-errors-on-kubernetes) -- [Consul troubleshooting guide](/docs/troubleshoot/common-errors) +- [Common Consul errors](/consul/docs/troubleshoot/common-errors#common-errors-on-kubernetes) +- [Consul troubleshooting guide](/consul/docs/troubleshoot/common-errors) - [Consul Discuss forum](https://discuss.hashicorp.com/) -[`ca_config`]: /docs/agent/config/config-files#connect_ca_config -[`ca_provider`]: /docs/agent/config/config-files#connect_ca_provider -[`/connect/ca/configuration`]: /api-docs/connect/ca#update-ca-configuration +[`ca_config`]: /consul/docs/agent/config/config-files#connect_ca_config +[`ca_provider`]: /consul/docs/agent/config/config-files#connect_ca_provider +[`/connect/ca/configuration`]: /consul/api-docs/connect/ca#update-ca-configuration diff --git a/website/content/docs/connect/ca/consul.mdx b/website/content/docs/connect/ca/consul.mdx index a2ea40b5d7..23d7f2ab4d 100644 --- a/website/content/docs/connect/ca/consul.mdx +++ b/website/content/docs/connect/ca/consul.mdx @@ -14,11 +14,11 @@ configured with a custom certificate and private key if needed. If Connect is enabled and no CA provider is specified, the built-in CA is the default provider used. The provider can be -[updated and rotated](/docs/connect/ca#root-certificate-rotation) +[updated and rotated](/consul/docs/connect/ca#root-certificate-rotation) at any point to migrate to a new provider. -> This page documents the specifics of the built-in CA provider. -Please read the [certificate management overview](/docs/connect/ca) +Please read the [certificate management overview](/consul/docs/connect/ca) page first to understand how Consul manages certificates with configurable CA providers. @@ -57,7 +57,7 @@ configuration file. [SPIFFE SVID signing certificate](https://github.com/spiffe/spiffe/blob/master/standards/X509-SVID.md) and the URI in the SAN must match the cluster identifier created at bootstrap with the ".consul" TLD. The cluster identifier can be found - using the [CA List Roots endpoint](/api-docs/connect/ca#list-ca-root-certificates). + using the [CA List Roots endpoint](/consul/api-docs/connect/ca#list-ca-root-certificates). @include 'http_api_connect_ca_common_options.mdx' @@ -69,7 +69,7 @@ the Consul CA provider to use a specific private key and root certificate. This is particularly useful if you have an external PKI system that doesn't currently integrate with Consul directly. -To view the current CA configuration, use the [Get CA Configuration endpoint](/api-docs/connect/ca#get-ca-configuration): +To view the current CA configuration, use the [Get CA Configuration endpoint](/consul/api-docs/connect/ca#get-ca-configuration): ```shell-session $ curl localhost:8500/v1/connect/ca/configuration @@ -89,8 +89,8 @@ Connect is enabled - the PrivateKey and RootCert fields have not been set, so th been generated (as seen above in the roots list). There are two ways to have the Consul CA use a custom private key and root certificate: -either through the `ca_config` section of the [Agent configuration](/docs/agent/config/config-files#connect_ca_config) (which can only be used during the cluster's -initial bootstrap) or through the [Update CA Configuration endpoint](/api-docs/connect/ca#update-ca-configuration). +either through the `ca_config` section of the [Agent configuration](/consul/docs/agent/config/config-files#connect_ca_config) (which can only be used during the cluster's +initial bootstrap) or through the [Update CA Configuration endpoint](/consul/api-docs/connect/ca#update-ca-configuration). Currently Consul requires that root certificates are valid [SPIFFE SVID Signing certificates](https://github.com/spiffe/spiffe/blob/master/standards/X509-SVID.md) and that the URI encoded in the SAN is the cluster identifier created at bootstrap with the ".consul" TLD. In this diff --git a/website/content/docs/connect/ca/index.mdx b/website/content/docs/connect/ca/index.mdx index be942b38f8..03502a7395 100644 --- a/website/content/docs/connect/ca/index.mdx +++ b/website/content/docs/connect/ca/index.mdx @@ -15,10 +15,10 @@ such as when a service needs a new certificate or during CA rotation events. The CA provider abstraction enables Consul to support multiple systems for storing and signing certificates. Consul ships with a -[built-in CA](/docs/connect/ca/consul) which generates and stores the +[built-in CA](/consul/docs/connect/ca/consul) which generates and stores the root certificate and private key on the Consul servers. Consul also has support for using -[Vault as a CA](/docs/connect/ca/vault). With Vault, the root certificate +[Vault as a CA](/consul/docs/connect/ca/vault). With Vault, the root certificate and private key material remain with the Vault cluster. ### CA and Certificate relationship @@ -42,15 +42,15 @@ datacenter. CA initialization happens automatically when a new Consul leader is elected as long as -[Connect is enabled](/docs/connect/configuration#agent-configuration), +[Connect is enabled](/consul/docs/connect/configuration#agent-configuration), and the CA system has not already been initialized. This initialization process will generate the initial root certificates and setup the internal Consul server state. For the initial bootstrap, the CA provider can be configured through the -[Agent configuration](/docs/agent/config/config-files#connect_ca_config). After +[Agent configuration](/consul/docs/agent/config/config-files#connect_ca_config). After initialization, the CA can only be updated through the -[Update CA Configuration API endpoint](/api-docs/connect/ca#update-ca-configuration). +[Update CA Configuration API endpoint](/consul/api-docs/connect/ca#update-ca-configuration). If a CA is already initialized, any changes to the CA configuration in the agent configuration file (including removing the configuration completely) will have no effect. @@ -62,7 +62,7 @@ be generated automatically. ## Viewing Root Certificates Root certificates can be queried with the -[list CA Roots endpoint](/api-docs/connect/ca#list-ca-root-certificates). +[list CA Roots endpoint](/consul/api-docs/connect/ca#list-ca-root-certificates). With this endpoint, you can see the list of currently trusted root certificates. When a cluster first initializes, this will only list one trusted root. Multiple roots may appear as part of @@ -97,7 +97,7 @@ $ curl http://localhost:8500/v1/connect/ca/roots ## CA Configuration After initialization, the CA provider configuration can be viewed with the -[Get CA Configuration API endpoint](/api-docs/connect/ca#get-ca-configuration). +[Get CA Configuration API endpoint](/consul/api-docs/connect/ca#get-ca-configuration). Consul will filter sensitive values from this endpoint depending on the provider in use, so the configuration may not be complete. @@ -115,7 +115,7 @@ $ curl http://localhost:8500/v1/connect/ca/configuration ``` The CA provider can be reconfigured using the -[Update CA Configuration API endpoint](/api-docs/connect/ca#update-ca-configuration). +[Update CA Configuration API endpoint](/consul/api-docs/connect/ca#update-ca-configuration). Specific options for reconfiguration can be found in the specific CA provider documentation in the sidebar to the left. @@ -148,7 +148,7 @@ certificate or CA provider has been set up, the new root becomes the active one and is immediately used for signing any new incoming certificate requests. If we check the [list CA roots -endpoint](/api-docs/connect/ca#list-ca-root-certificates) after updating the +endpoint](/consul/api-docs/connect/ca#list-ca-root-certificates) after updating the configuration with a new root certificate, we can see both the old and new root certificates are present, and the currently active root has an intermediate certificate which has been generated and cross-signed automatically by the old @@ -231,7 +231,7 @@ to. ### Recovering From Expired Certificates If the built-in CA provider is misconfigured or unavailable, Consul service mesh requests eventually stop functioning due to expiration of intermediate and root certificates. To recover manually, use the -[CLI helper](/commands/tls/ca#consul-tls-ca-create) to generate CA certificates. +[CLI helper](/consul/commands/tls/ca#consul-tls-ca-create) to generate CA certificates. #### Example - Regenerating the built in CA @@ -242,9 +242,9 @@ $ consul tls ca create -cluster-id test -common-name "Consul Agent CA" -days=365 ``` The example above generates a new CA with a validity of 365 days. The cluster-id argument is specific to each cluster and can be looked up by examining the `TrustDomain` field in -the [List CA Roots](/api-docs/connect/ca#list-ca-root-certificates) endpoint. +the [List CA Roots](/consul/api-docs/connect/ca#list-ca-root-certificates) endpoint. The contents of the generated cert and private key files from the above step should then be used with -the [Update CA Configuration](/api-docs/connect/ca#update-ca-configuration) endpoint. Once the CA configuration is +the [Update CA Configuration](/consul/api-docs/connect/ca#update-ca-configuration) endpoint. Once the CA configuration is updated on the primary datacenter, all secondary datacenters will pick up the changes and regenerate their intermediate and leaf certificates, after which any new requests that require certificate verification will succeed. diff --git a/website/content/docs/connect/ca/vault.mdx b/website/content/docs/connect/ca/vault.mdx index ee6ebf114b..54fe5f4b67 100644 --- a/website/content/docs/connect/ca/vault.mdx +++ b/website/content/docs/connect/ca/vault.mdx @@ -8,14 +8,14 @@ description: >- # Vault as a Service Mesh Certificate Authority You can configure Consul to use [Vault](https://www.vaultproject.io/) as the certificate authority (CA) so that Vault can manage and sign certificates distributed to services in the mesh. -The Vault CA provider uses the [Vault PKI secrets engine](https://www.vaultproject.io/docs/secrets/pki) to generate and sign certificates. +The Vault CA provider uses the [Vault PKI secrets engine](/vault/docs/secrets/pki) to generate and sign certificates. This page describes how configure the Vault CA provider. > **Tutorial:** Complete the [Vault as Consul Service Mesh Certification Authority](/consul/tutorials/vault-secure/vault-pki-consul-connect-ca) tutorial for hands-on guidance on how to configure Vault as the Consul service mesh certification authority. ## Requirements -- Refer to [Service Mesh Certificate Authority Overview](/docs/connect/ca) for important background information about how Consul manages certificates with configurable CA providers. +- Refer to [Service Mesh Certificate Authority Overview](/consul/docs/connect/ca) for important background information about how Consul manages certificates with configurable CA providers. - Vault 0.10.3 to 1.10.x. @@ -27,7 +27,7 @@ You can enable Vault as the CA by configuring Consul to use `"vault"` as the CA and including the required provider configuration options. You can provide the CA configuration in the server agents' configuration file or in the body of a `PUT` request to the -[`/connect/ca/configuration`](/api-docs/connect/ca#update-ca-configuration) API endpoint. +[`/connect/ca/configuration`](/consul/api-docs/connect/ca#update-ca-configuration) API endpoint. Refer to the [Configuration Reference](#configuration-reference) for details about configuration options and for example use cases. The following example shows the required configurations for a default implementation: @@ -83,14 +83,14 @@ The key after the slash refers to the corresponding option name in the agent con - `Token` / `token` (`string: ""`) - A token for accessing Vault. This is write-only and will not be exposed when reading the CA configuration. This token must have [proper privileges](#vault-acl-policies) for the PKI - paths configured. In Consul 1.8.5 and later, if the token has the [renewable](https://www.vaultproject.io/api-docs/auth/token#renewable) + paths configured. In Consul 1.8.5 and later, if the token has the [renewable](/vault/api-docs/auth/token#renewable) flag set, Consul will attempt to renew its lease periodically after half the duration has expired. !> **Warning:** You must either provide a token or configure an auth method below. - `AuthMethod` / `auth_method` (`map: nil`) - Vault auth method to use for logging in to Vault. - Please see [Vault Auth Methods](https://www.vaultproject.io/docs/auth) for more information + Please see [Vault Auth Methods](/vault/docs/auth) for more information on how to configure individual auth methods. If auth method is provided, Consul will obtain a new token from Vault when the token can no longer be renewed. @@ -100,7 +100,7 @@ The key after the slash refers to the corresponding option name in the agent con If not provided the auth method type will be used as the mount path. - `Params`/`params` (`map: nil`) - The parameters to configure the auth method. Please see - [Vault Auth Methods](https://www.vaultproject.io/docs/auth) for information on how to configure the + [Vault Auth Methods](/vault/docs/auth) for information on how to configure the auth method you wish to use. If using the Kubernetes auth method, Consul will read the service account token from the default mount path `/var/run/secrets/kubernetes.io/serviceaccount/token` if the `jwt` parameter @@ -112,7 +112,7 @@ The key after the slash refers to the corresponding option name in the agent con If the path does not exist, Consul will mount a new PKI secrets engine at the specified path with the `RootCertTTL` value as the root certificate's TTL. If the `RootCertTTL` is not set, - a [`max_lease_ttl`](https://www.vaultproject.io/api-docs/system/mounts) + a [`max_lease_ttl`](/vault/api-docs/system/mounts) of 87600 hours, or 10 years is applied by default as of Consul 1.11 and later. Prior to Consul 1.11, the root certificate TTL was set to 8760 hour, or 1 year, and was not configurable. The root certificate will expire at the end of the specified period. @@ -174,7 +174,7 @@ The key after the slash refers to the corresponding option name in the agent con ### Root and Intermediate PKI Paths The Vault CA provider uses two separately configured -[PKI secrets engines](https://www.vaultproject.io/docs/secrets/pki) +[PKI secrets engines](/vault/docs/secrets/pki) for managing Consul service mesh certificates. The `RootPKIPath` is the PKI engine for the root certificate. diff --git a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx index 71b3f50d2e..dbbf0d4fc3 100644 --- a/website/content/docs/connect/cluster-peering/create-manage-peering.mdx +++ b/website/content/docs/connect/cluster-peering/create-manage-peering.mdx @@ -12,7 +12,7 @@ A peering token enables cluster peering between different datacenters. Once you ## Create a peering connection -Cluster peering is enabled by default on Consul servers as of v1.14. For additional information, including options to disable cluster peering, refer to [Configuration Files](/docs/agent/config/config-files). +Cluster peering is enabled by default on Consul servers as of v1.14. For additional information, including options to disable cluster peering, refer to [Configuration Files](/consul/docs/agent/config/config-files). The process to create a peering connection is a sequence with multiple steps: @@ -34,7 +34,7 @@ Every time you generate a peering token, a single-use establishment secret is em -In `cluster-01`, use the [`/peering/token` endpoint](/api-docs/peering#generate-a-peering-token) to issue a request for a peering token. +In `cluster-01`, use the [`/peering/token` endpoint](/consul/api-docs/peering#generate-a-peering-token) to issue a request for a peering token. ```shell-session $ curl --request POST --data '{"Peer":"cluster-02"}' --url http://localhost:8500/v1/peering/token @@ -58,7 +58,7 @@ Create a JSON file that contains the first cluster's name and the peering token. -In `cluster-01`, use the [`consul peering generate-token` command](/commands/peering/generate-token) to issue a request for a peering token. +In `cluster-01`, use the [`consul peering generate-token` command](/consul/commands/peering/generate-token) to issue a request for a peering token. ```shell-session $ consul peering generate-token -name cluster-02 @@ -87,13 +87,13 @@ Next, use the peering token to establish a secure connection between the cluster -In one of the client agents in "cluster-02," use `peering_token.json` and the [`/peering/establish` endpoint](/api-docs/peering#establish-a-peering-connection) to establish the peering connection. This endpoint does not generate an output unless there is an error. +In one of the client agents in "cluster-02," use `peering_token.json` and the [`/peering/establish` endpoint](/consul/api-docs/peering#establish-a-peering-connection) to establish the peering connection. This endpoint does not generate an output unless there is an error. ```shell-session $ curl --request POST --data @peering_token.json http://127.0.0.1:8500/v1/peering/establish ``` -When you connect server agents through cluster peering, their default behavior is to peer to the `default` partition. To establish peering connections for other partitions through server agents, you must add the `Partition` field to `peering_token.json` and specify the partitions you want to peer. For additional configuration information, refer to [Cluster Peering - HTTP API](/api-docs/peering). +When you connect server agents through cluster peering, their default behavior is to peer to the `default` partition. To establish peering connections for other partitions through server agents, you must add the `Partition` field to `peering_token.json` and specify the partitions you want to peer. For additional configuration information, refer to [Cluster Peering - HTTP API](/consul/api-docs/peering). You can dial the `peering/establish` endpoint once per peering token. Peering tokens cannot be reused after being used to establish a connection. If you need to re-establish a connection, you must generate a new peering token. @@ -101,7 +101,7 @@ You can dial the `peering/establish` endpoint once per peering token. Peering to -In one of the client agents in "cluster-02," issue the [`consul peering establish` command](/commands/peering/establish) and specify the token generated in the previous step. The command establishes the peering connection. +In one of the client agents in "cluster-02," issue the [`consul peering establish` command](/consul/commands/peering/establish) and specify the token generated in the previous step. The command establishes the peering connection. The commands prints "Successfully established peering connection with cluster-01" after the connection is established. ```shell-session @@ -110,7 +110,7 @@ $ consul peering establish -name cluster-01 -peering-token token-from-generate When you connect server agents through cluster peering, they peer their default partitions. To establish peering connections for other partitions through server agents, you must add the `-partition` flag to the `establish` command and specify the partitions you want to peer. -For additional configuration information, refer to [`consul peering establish` command](/commands/peering/establish) . +For additional configuration information, refer to [`consul peering establish` command](/consul/commands/peering/establish) . You can run the `peering establish` command once per peering token. Peering tokens cannot be reused after being used to establish a connection. @@ -205,11 +205,11 @@ Read access to all imported services is granted using either of the following ru - `service:write` permissions for any service in the sidecar's partition. - `service:read` and `node:read` for all services and nodes, respectively, in sidecar's namespace and partition. For Consul Enterprise, access is granted to all imported services in the service's partition. -These permissions are satisfied when using a [service identity](/docs/security/acl/acl-roles#service-identities). +These permissions are satisfied when using a [service identity](/consul/docs/security/acl/acl-roles#service-identities). -Example rule files can be found in [Reading Servers](/docs/connect/config-entries/exported-services#reading-services) in the `exported-services` config entry documentation. +Example rule files can be found in [Reading Servers](/consul/docs/connect/config-entries/exported-services#reading-services) in the `exported-services` config entry documentation. -Refer to [ACLs System Overview](/docs/security/acl) for more information on ACLs and their setup. +Refer to [ACLs System Overview](/consul/docs/security/acl) for more information on ACLs and their setup. ## Manage peering connections @@ -222,7 +222,7 @@ You can list all active peering connections in a cluster. -After you establish a peering connection, [query the `/peerings/` endpoint](/api-docs/peering#list-all-peerings) to get a list of all peering connections. For example, the following command requests a list of all peering connections on `localhost` and returns the information as a series of JSON objects: +After you establish a peering connection, [query the `/peerings/` endpoint](/consul/api-docs/peering#list-all-peerings) to get a list of all peering connections. For example, the following command requests a list of all peering connections on `localhost` and returns the information as a series of JSON objects: ```shell-session $ curl http://127.0.0.1:8500/v1/peerings @@ -258,7 +258,7 @@ $ curl http://127.0.0.1:8500/v1/peerings -After you establish a peering connection, run the [`consul peering list`](/commands/peering/list) command to get a list of all peering connections. +After you establish a peering connection, run the [`consul peering list`](/consul/commands/peering/list) command to get a list of all peering connections. For example, the following command requests a list of all peering connections and returns the information in a table: ```shell-session @@ -285,7 +285,7 @@ You can get information about individual peering connections between clusters. -After you establish a peering connection, [query the `/peering/` endpoint](/api-docs/peering#read-a-peering-connection) to get peering information about for a specific cluster. For example, the following command requests peering connection information for "cluster-02" and returns the info as a JSON object: +After you establish a peering connection, [query the `/peering/` endpoint](/consul/api-docs/peering#read-a-peering-connection) to get peering information about for a specific cluster. For example, the following command requests peering connection information for "cluster-02" and returns the info as a JSON object: ```shell-session $ curl http://127.0.0.1:8500/v1/peering/cluster-02 @@ -307,7 +307,7 @@ $ curl http://127.0.0.1:8500/v1/peering/cluster-02 -After you establish a peering connection, run the [`consul peering read`](/commands/peering/list) command to get peering information about for a specific cluster. +After you establish a peering connection, run the [`consul peering read`](/consul/commands/peering/list) command to get peering information about for a specific cluster. For example, the following command requests peering connection information for "cluster-02": ```shell-session @@ -344,7 +344,7 @@ In the Consul UI, click **Peers**. The UI lists peering connections you created You can check the status of your peering connection to perform health checks. -To confirm that the peering connection between your clusters remains healthy, query the [`health/service` endpoint](/api-docs/health) of one cluster from the other cluster. For example, in "cluster-02," query the endpoint and add the `peer=cluster-01` query parameter to the end of the URL. +To confirm that the peering connection between your clusters remains healthy, query the [`health/service` endpoint](/consul/api-docs/health) of one cluster from the other cluster. For example, in "cluster-02," query the endpoint and add the `peer=cluster-01` query parameter to the end of the URL. ```shell-session $ curl \ @@ -360,7 +360,7 @@ You can disconnect the peered clusters by deleting their connection. Deleting a -In "cluster-01," request the deletion through the [`/peering/ endpoint`](/api-docs/peering#delete-a-peering-connection). +In "cluster-01," request the deletion through the [`/peering/ endpoint`](/consul/api-docs/peering#delete-a-peering-connection). ```shell-session $ curl --request DELETE http://127.0.0.1:8500/v1/peering/cluster-02 @@ -369,7 +369,7 @@ $ curl --request DELETE http://127.0.0.1:8500/v1/peering/cluster-02 -In "cluster-01," request the deletion through the [`consul peering delete`](/commands/peering/list) command. +In "cluster-01," request the deletion through the [`consul peering delete`](/consul/commands/peering/list) command. ```shell-session $ consul peering delete -name cluster-02 @@ -393,7 +393,7 @@ The following sections describe how to enable L7 traffic management features bet ### Service resolvers for redirects and failover -As of Consul v1.14, you can use [dynamic traffic management](/consul/docs/connect/l7-traffic) to configure your service mesh so that services automatically failover and redirect between peers. The following examples update the [`service-resolver` config entry](/docs/connect/config-entries/) in `cluster-01` so that Consul redirects traffic intended for the `frontend` service to a backup instance in peer `cluster-02` when it detects multiple connection failures. +As of Consul v1.14, you can use [dynamic traffic management](/consul/docs/connect/l7-traffic) to configure your service mesh so that services automatically failover and redirect between peers. The following examples update the [`service-resolver` config entry](/consul/docs/connect/config-entries/) in `cluster-01` so that Consul redirects traffic intended for the `frontend` service to a backup instance in peer `cluster-02` when it detects multiple connection failures. diff --git a/website/content/docs/connect/cluster-peering/index.mdx b/website/content/docs/connect/cluster-peering/index.mdx index 184598c546..77f4b8f4c7 100644 --- a/website/content/docs/connect/cluster-peering/index.mdx +++ b/website/content/docs/connect/cluster-peering/index.mdx @@ -18,11 +18,11 @@ Cluster peering is a process that allows Consul clusters to communicate with eac 1. Export services between clusters. 1. Create intentions to authorize services for peers. -This process establishes cluster peering between two [admin partitions](/docs/enterprise/admin-partitions). Deployments without an Enterprise license can still use cluster peering because every datacenter automatically includes a `default` partition. +This process establishes cluster peering between two [admin partitions](/consul/docs/enterprise/admin-partitions). Deployments without an Enterprise license can still use cluster peering because every datacenter automatically includes a `default` partition. -For detailed instructions on establishing cluster peering connections, refer to [Create and Manage Peering Connections](/docs/connect/cluster-peering/create-manage-peering). +For detailed instructions on establishing cluster peering connections, refer to [Create and Manage Peering Connections](/consul/docs/connect/cluster-peering/create-manage-peering). -> To learn how to peer clusters and connect services across peers in AWS Elastic Kubernetes Service (EKS) environments, complete the [Consul Cluster Peering on Kubernetes tutorial](https://learn.hashicorp.com/tutorials/consul/cluster-peering-aws?utm_source=docs). +> To learn how to peer clusters and connect services across peers in AWS Elastic Kubernetes Service (EKS) environments, complete the [Consul Cluster Peering on Kubernetes tutorial](/consul/tutorials/developer-mesh/cluster-peering-aws?utm_source=docs). ### Differences between WAN federation and cluster peering @@ -47,6 +47,6 @@ Regardless of whether you connect your clusters through WAN federation or cluste Consider the following technical constraints: - Services with node, instance, and check definitions totaling more than 8MB cannot be exported to a peer. -- Two admin partitions in the same datacenter cannot be peered. Use [`exported-services`](/docs/connect/config-entries/exported-services#exporting-services-to-peered-clusters) directly. -- The `consul intention` CLI command is not supported. To manage intentions that specify services in peered clusters, use [configuration entries](/docs/connect/config-entries/service-intentions). +- Two admin partitions in the same datacenter cannot be peered. Use [`exported-services`](/consul/docs/connect/config-entries/exported-services#exporting-services-to-peered-clusters) directly. +- The `consul intention` CLI command is not supported. To manage intentions that specify services in peered clusters, use [configuration entries](/consul/docs/connect/config-entries/service-intentions). - Accessing key/value stores across peers is not supported. diff --git a/website/content/docs/connect/cluster-peering/k8s.mdx b/website/content/docs/connect/cluster-peering/k8s.mdx index ca419d6571..570442fd4a 100644 --- a/website/content/docs/connect/cluster-peering/k8s.mdx +++ b/website/content/docs/connect/cluster-peering/k8s.mdx @@ -10,8 +10,8 @@ description: >- To establish a cluster peering connection on Kubernetes, you need to enable several pre-requisite values in the Helm chart and create custom resource definitions (CRDs) for each side of the peering. The following Helm values are mandatory for cluster peering: -- [`global.tls.enabled = true`](/docs/k8s/helm#v-global-tls-enabled) -- [`meshGateway.enabled = true`](/docs/k8s/helm#v-meshgateway-enabled) +- [`global.tls.enabled = true`](/consul/docs/k8s/helm#v-global-tls-enabled) +- [`meshGateway.enabled = true`](/consul/docs/k8s/helm#v-meshgateway-enabled) The following CRDs are used to create and manage a peering connection: @@ -21,7 +21,7 @@ The following CRDs are used to create and manage a peering connection: Peering connections, including both data plane and control plane traffic, is routed through mesh gateways. As of Consul v1.14, you can also [implement service failovers and redirects to control traffic](/consul/docs/connect/l7-traffic) between peers. -> To learn how to peer clusters and connect services across peers in AWS Elastic Kubernetes Service (EKS) environments, complete the [Consul Cluster Peering on Kubernetes tutorial](https://learn.hashicorp.com/tutorials/consul/cluster-peering-aws?utm_source=docs). +> To learn how to peer clusters and connect services across peers in AWS Elastic Kubernetes Service (EKS) environments, complete the [Consul Cluster Peering on Kubernetes tutorial](/consul/tutorials/developer-mesh/cluster-peering-aws?utm_source=docs). ## Prerequisites @@ -380,7 +380,7 @@ The examples described in this section demonstrate how to export a service named -1. Add the `"consul.hashicorp.com/connect-inject": "true"` annotation to your service's pods before deploying the workload so that the services in `cluster-01` can dial `backend` in `cluster-02`. To dial the upstream service from an application, configure the application so that that requests are sent to the correct DNS name as specified in [Service Virtual IP Lookups](/docs/discovery/dns#service-virtual-ip-lookups). In the following example, the annotation that allows the workload to join the mesh and the configuration provided to the workload that enables the workload to dial the upstream service using the correct DNS name is highlighted. [Service Virtual IP Lookups for Consul Enterprise](/docs/discovery/dns#service-virtual-ip-lookups-for-consul-enterprise) details how you would similarly format a DNS name including partitions and namespaces. +1. Add the `"consul.hashicorp.com/connect-inject": "true"` annotation to your service's pods before deploying the workload so that the services in `cluster-01` can dial `backend` in `cluster-02`. To dial the upstream service from an application, configure the application so that that requests are sent to the correct DNS name as specified in [Service Virtual IP Lookups](/consul/docs/discovery/dns#service-virtual-ip-lookups). In the following example, the annotation that allows the workload to join the mesh and the configuration provided to the workload that enables the workload to dial the upstream service using the correct DNS name is highlighted. [Service Virtual IP Lookups for Consul Enterprise](/consul/docs/discovery/dns#service-virtual-ip-lookups-for-consul-enterprise) details how you would similarly format a DNS name including partitions and namespaces. diff --git a/website/content/docs/connect/config-entries/exported-services.mdx b/website/content/docs/connect/config-entries/exported-services.mdx index cbc459e9e2..d3a793c891 100644 --- a/website/content/docs/connect/config-entries/exported-services.mdx +++ b/website/content/docs/connect/config-entries/exported-services.mdx @@ -7,7 +7,7 @@ description: >- # Exported Services Configuration Entry -This topic describes the `exported-services` configuration entry type. The `exported-services` configuration entry enables Consul to export service instances to other clusters from a single file and connect services across clusters. For additional information, refer to [Cluster Peering](/docs/connect/cluster-peering) and [Admin Partitions](/docs/enterprise/admin-partitions). +This topic describes the `exported-services` configuration entry type. The `exported-services` configuration entry enables Consul to export service instances to other clusters from a single file and connect services across clusters. For additional information, refer to [Cluster Peering](/consul/docs/connect/cluster-peering) and [Admin Partitions](/consul/docs/enterprise/admin-partitions). -> **v1.11.0+:** This config entry is supported in Consul versions 1.11.0+. @@ -23,10 +23,10 @@ You can configure the settings defined in the `exported-services` configuration ## Usage 1. Verify that your datacenter meets the conditions specified in the [Requirements](#requirements). -1. Specify the `exported-services` configuration in the agent configuration file (see [`config_entries`](/docs/agent/config/config-files#config_entries)) as described in [Configuration](#configuration). +1. Specify the `exported-services` configuration in the agent configuration file (see [`config_entries`](/consul/docs/agent/config/config-files#config_entries)) as described in [Configuration](#configuration). 1. Apply the configuration using one of the following methods: - - Kubernetes CRD: Refer to the [Custom Resource Definitions](/docs/k8s/crds) documentation for details. - - Issue the `consul config write` command: Refer to the [Consul Config Write](/commands/config/write) documentation for details. + - Kubernetes CRD: Refer to the [Custom Resource Definitions](/consul/docs/k8s/crds) documentation for details. + - Issue the `consul config write` command: Refer to the [Consul Config Write](/consul/commands/config/write) documentation for details. ## Configuration @@ -891,4 +891,4 @@ partition "frontend" { -For additional information, refer to [Health HTTP Endpoint](/api-docs/health). +For additional information, refer to [Health HTTP Endpoint](/consul/api-docs/health). diff --git a/website/content/docs/connect/config-entries/index.mdx b/website/content/docs/connect/config-entries/index.mdx index 23e3d0bd23..6d29a27cc3 100644 --- a/website/content/docs/connect/config-entries/index.mdx +++ b/website/content/docs/connect/config-entries/index.mdx @@ -11,44 +11,44 @@ Configuration entries can be used to configure the behavior of Consul Connect. The following configuration entries are supported: -- [Ingress Gateway](/docs/connect/config-entries/ingress-gateway) - defines the +- [Ingress Gateway](/consul/docs/connect/config-entries/ingress-gateway) - defines the configuration for an ingress gateway -- [Mesh](/docs/connect/config-entries/mesh) - controls +- [Mesh](/consul/docs/connect/config-entries/mesh) - controls mesh-wide configuration that applies across namespaces and federated datacenters. -- [Exported Services](/docs/connect/config-entries/exported-services) - enables +- [Exported Services](/consul/docs/connect/config-entries/exported-services) - enables Consul to export service instances to other peers or to other admin partitions local or remote to the datacenter. -- [Proxy Defaults](/docs/connect/config-entries/proxy-defaults) - controls +- [Proxy Defaults](/consul/docs/connect/config-entries/proxy-defaults) - controls proxy configuration -- [Service Defaults](/docs/connect/config-entries/service-defaults) - configures +- [Service Defaults](/consul/docs/connect/config-entries/service-defaults) - configures defaults for all the instances of a given service -- [Service Intentions](/docs/connect/config-entries/service-intentions) - defines - the [intentions](/docs/connect/intentions) for a destination service +- [Service Intentions](/consul/docs/connect/config-entries/service-intentions) - defines + the [intentions](/consul/docs/connect/intentions) for a destination service -- [Service Resolver](/docs/connect/config-entries/service-resolver) - matches +- [Service Resolver](/consul/docs/connect/config-entries/service-resolver) - matches service instances with a specific Connect upstream discovery requests -- [Service Router](/docs/connect/config-entries/service-router) - defines +- [Service Router](/consul/docs/connect/config-entries/service-router) - defines where to send layer 7 traffic based on the HTTP route -- [Service Splitter](/docs/connect/config-entries/service-splitter) - defines +- [Service Splitter](/consul/docs/connect/config-entries/service-splitter) - defines how to divide requests for a single HTTP route based on percentages -- [Terminating Gateway](/docs/connect/config-entries/terminating-gateway) - defines the +- [Terminating Gateway](/consul/docs/connect/config-entries/terminating-gateway) - defines the services associated with terminating gateway ## Managing Configuration Entries -See [Agent - Config Entries](/docs/agent/config-entries). +See [Agent - Config Entries](/consul/docs/agent/config-entries). ## Using Configuration Entries For Service Defaults Outside of Kubernetes, when the agent is -[configured](/docs/agent/config/config-files#enable_central_service_config) to enable +[configured](/consul/docs/agent/config/config-files#enable_central_service_config) to enable central service configurations, it will look for service configuration defaults that match a registering service instance. If it finds any, the agent will merge those defaults with the service instance configuration. This allows for things diff --git a/website/content/docs/connect/config-entries/ingress-gateway.mdx b/website/content/docs/connect/config-entries/ingress-gateway.mdx index 7cee38cce6..ee94412661 100644 --- a/website/content/docs/connect/config-entries/ingress-gateway.mdx +++ b/website/content/docs/connect/config-entries/ingress-gateway.mdx @@ -13,17 +13,17 @@ This topic provides reference information for the `ingress-gateway` configuratio You can define an `ingress-gateway` configuration entry to connect the Consul service mesh to a set of external services. The specification for ingress gateways include a `listeners` configuration, which exposes the service mesh to the external services. Use camel case (`IngressGateway`) to declare an ingress gateway configuration entry on Kubernetes. -Refer to the [Kubernetes Ingress Gateway](/docs/k8s/connect/ingress-gateways) documentation for information about configuring ingress gateways on Kubernetes. +Refer to the [Kubernetes Ingress Gateway](/consul/docs/k8s/connect/ingress-gateways) documentation for information about configuring ingress gateways on Kubernetes. -For other platforms, see [Ingress Gateway](/docs/connect/gateways/ingress-gateway). +For other platforms, see [Ingress Gateway](/consul/docs/connect/gateways/ingress-gateway). ## Usage 1. Verify that your datacenter meets the conditions specified in the [Requirements](#requirements). 1. Create a file containing the configuration entry settings (see [Configuration](#configuration)). 1. Apply the configuration settings using one of the following methods: - - Kubernetes CRD: Refer to the [Custom Resource Definitions](/docs/k8s/crds) documentation for details. - - Issue the `consul config write` command: Refer to the [Consul Config Write](/commands/config/write) documentation for details. + - Kubernetes CRD: Refer to the [Custom Resource Definitions](/consul/docs/k8s/crds) documentation for details. + - Issue the `consul config write` command: Refer to the [Consul Config Write](/consul/commands/config/write) documentation for details. ## Configuration @@ -156,7 +156,7 @@ Refer to the [Available Fields](#available-fields) section for complete informat ### Scope -[Configuration entries](/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies across the default partition of all federated Consul datacenters. If ingress gateways in different Consul datacenters need to route to different sets of services within their datacenter then the ingress gateways **must** be registered with different names or partitions. See [Ingress Gateway](/docs/connect/gateways/ingress-gateway) for more information. +[Configuration entries](/consul/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies across the default partition of all federated Consul datacenters. If ingress gateways in different Consul datacenters need to route to different sets of services within their datacenter then the ingress gateways **must** be registered with different names or partitions. See [Ingress Gateway](/consul/docs/connect/gateways/ingress-gateway) for more information. ### Wildcard Service Specification @@ -170,18 +170,18 @@ A wildcard specifier provides the following properties for an ingress gateway: - All services with the same - [protocol](/docs/connect/config-entries/ingress-gateway#protocol) as the + [protocol](/consul/docs/connect/config-entries/ingress-gateway#protocol) as the listener will be routable. - The ingress gateway will route traffic based on the host/authority header, expecting a value matching `.ingress.*`, or if using namespaces, `.ingress..*`. This matches the [Consul DNS - ingress subdomain](/docs/discovery/dns#ingress-service-lookups). + ingress subdomain](/consul/docs/discovery/dns#ingress-service-lookups). A wildcard specifier cannot be set on a listener of protocol `tcp`. ### ACLs -Configuration entries may be protected by [ACLs](/docs/security/acl). +Configuration entries may be protected by [ACLs](/consul/docs/security/acl). Reading an `ingress-gateway` config entry requires `service:read` on the `Name` field of the config entry. @@ -195,7 +195,7 @@ The following examples describe possible use-cases for ingress gateway configura #### TCP listener -The following example sets up a TCP listener on an ingress gateway named `us-east-ingress` to proxy traffic to the `db` service. The Consul Enterprise version also posits the gateway listener inside the `default` [namespace](/docs/enterprise/namespaces) and the `team-frontend` [admin partition](/docs/enterprise/admin-partitions): +The following example sets up a TCP listener on an ingress gateway named `us-east-ingress` to proxy traffic to the `db` service. The Consul Enterprise version also posits the gateway listener inside the `default` [namespace](/consul/docs/enterprise/namespaces) and the `team-frontend` [admin partition](/consul/docs/enterprise/admin-partitions): @@ -327,8 +327,8 @@ In the following example, two listeners are configured on an ingress gateway nam The Consul Enterprise version implements the following additional configurations: -- The ingress gateway is set up in the `default` [namespace](/docs/enterprise/namespaces) and proxies traffic to all services in the `frontend` namespace. -- The `api` and `web` services are proxied to team-specific [admin partitions](/docs/enterprise/admin-partitions): +- The ingress gateway is set up in the `default` [namespace](/consul/docs/enterprise/namespaces) and proxies traffic to all services in the `frontend` namespace. +- The `api` and `web` services are proxied to team-specific [admin partitions](/consul/docs/enterprise/admin-partitions): diff --git a/website/content/docs/connect/config-entries/mesh.mdx b/website/content/docs/connect/config-entries/mesh.mdx index 39265abcbe..7900a8104a 100644 --- a/website/content/docs/connect/config-entries/mesh.mdx +++ b/website/content/docs/connect/config-entries/mesh.mdx @@ -103,7 +103,7 @@ spec: -Note that the Kubernetes example does not include a `partition` field. Configuration entries are applied on Kubernetes using [custom resource definitions (CRD)](/docs/k8s/crds), which can only be scoped to their own partition. +Note that the Kubernetes example does not include a `partition` field. Configuration entries are applied on Kubernetes using [custom resource definitions (CRD)](/consul/docs/k8s/crds), which can only be scoped to their own partition. ### Mesh Destinations Only @@ -184,7 +184,7 @@ spec: -Note that the Kubernetes example does not include a `partition` field. Configuration entries are applied on Kubernetes using [custom resource definitions (CRD)](/docs/k8s/crds), which can only be scoped to their own partition. +Note that the Kubernetes example does not include a `partition` field. Configuration entries are applied on Kubernetes using [custom resource definitions (CRD)](/consul/docs/k8s/crds), which can only be scoped to their own partition. ### Peer Through Mesh Gateways @@ -264,7 +264,7 @@ spec: -Note that the Kubernetes example does not include a `partition` field. Configuration entries are applied on Kubernetes using [custom resource definitions (CRD)](/docs/k8s/crds), which can only be scoped to their own partition. +Note that the Kubernetes example does not include a `partition` field. Configuration entries are applied on Kubernetes using [custom resource definitions (CRD)](/consul/docs/k8s/crds), which can only be scoped to their own partition. ## Available Fields @@ -459,7 +459,7 @@ Note that the Kubernetes example does not include a `partition` field. Configura ## ACLs -Configuration entries may be protected by [ACLs](/docs/security/acl). +Configuration entries may be protected by [ACLs](/consul/docs/security/acl). Reading a `mesh` config entry requires no specific privileges. diff --git a/website/content/docs/connect/config-entries/proxy-defaults.mdx b/website/content/docs/connect/config-entries/proxy-defaults.mdx index 2e361a58c8..5ac09c102f 100644 --- a/website/content/docs/connect/config-entries/proxy-defaults.mdx +++ b/website/content/docs/connect/config-entries/proxy-defaults.mdx @@ -8,7 +8,7 @@ description: >- # Proxy Defaults Configuration Entry The `proxy-defaults` configuration entry (`ProxyDefaults` on Kubernetes) allows you to globally configure passthrough Envoy settings for proxies in the service mesh, including both sidecars and gateways. -It is different from the [`mesh` configuration entry](/docs/connect/config-entries/mesh), which sets Consul features for cluster peering, transparent proxy, and TLS behavior that also affect Consul servers. +It is different from the [`mesh` configuration entry](/consul/docs/connect/config-entries/mesh), which sets Consul features for cluster peering, transparent proxy, and TLS behavior that also affect Consul servers. Only one global entry is supported. For Consul Enterprise, only the global entry in the `default` partition is recognized. @@ -18,17 +18,17 @@ For Consul Enterprise, only the global entry in the `default` partition is recog You can customize some service registration settings for service mesh proxies centrally using the `proxy-defaults` configuration entry in the `kind` field. You can still override this centralized configuration for specific services -with the [`service-defaults`](/docs/connect/config-entries/service-defaults) +with the [`service-defaults`](/consul/docs/connect/config-entries/service-defaults) configuration entry `kind` or for individual proxy instances in their [sidecar -service definitions](/docs/connect/registration/sidecar-service). +service definitions](/consul/docs/connect/registration/sidecar-service). ## Usage 1. Verify that your datacenter meets the conditions specified in the [Requirements](#requirements). 1. Determine the settings you want to implement (see [Configuration](#configuration)). You can create a file containing the configuration or pass them to the state store directly to apply the configuration. 1. Apply the configuration using one of the following methods: - - Kubernetes CRD: Refer to the [Custom Resource Definitions](/docs/k8s/crds) documentation for details. - - Issue the `consul config write` command: Refer to the [Consul Config Write](/commands/config/write) documentation for details. + - Kubernetes CRD: Refer to the [Custom Resource Definitions](/consul/docs/k8s/crds) documentation for details. + - Issue the `consul config write` command: Refer to the [Consul Config Write](/consul/commands/config/write) documentation for details. ## Configuration @@ -645,7 +645,7 @@ spec: ### Access Logs The following example is a minimal configuration for enabling access logs for all proxies. -Refer to [access logs](/docs/connect/observability/access-logs) for advanced configurations. +Refer to [access logs](/consul/docs/connect/observability/access-logs) for advanced configurations. @@ -720,7 +720,7 @@ spec: ## ACLs -Configuration entries may be protected by [ACLs](/docs/security/acl). +Configuration entries may be protected by [ACLs](/consul/docs/security/acl). Reading a `proxy-defaults` config entry requires no specific privileges. diff --git a/website/content/docs/connect/config-entries/service-intentions.mdx b/website/content/docs/connect/config-entries/service-intentions.mdx index 4b4deea2b7..619b4fb9fe 100644 --- a/website/content/docs/connect/config-entries/service-intentions.mdx +++ b/website/content/docs/connect/config-entries/service-intentions.mdx @@ -14,7 +14,7 @@ authorization for both networking layer 4 (e.g. TCP) and networking layer 7 (e.g. HTTP). Service intentions config entries represent a collection of -[intentions](/docs/connect/intentions) sharing a specific destination. All +[intentions](/consul/docs/connect/intentions) sharing a specific destination. All intentions governing access to a specific destination are stored in a single `service-intentions` config entry. @@ -27,8 +27,8 @@ global setting) by defining a low precedence intention for that destination. L7 intentions within a config entry are restricted to only destination services that define their protocol as HTTP-based via a corresponding -[`service-defaults`](/docs/connect/config-entries/service-defaults) config entry -or globally via [`proxy-defaults`](/docs/connect/config-entries/proxy-defaults) . +[`service-defaults`](/consul/docs/connect/config-entries/service-defaults) config entry +or globally via [`proxy-defaults`](/consul/docs/connect/config-entries/proxy-defaults) . ## Sample Config Entries @@ -718,7 +718,7 @@ spec: ## ACLs -Configuration entries may be protected by [ACLs](/docs/security/acl). +Configuration entries may be protected by [ACLs](/consul/docs/security/acl). Reading a `service-intentions` config entry requires `intentions:read` on the resource. @@ -726,7 +726,7 @@ Creating, updating, or deleting a `service-intentions` config entry requires `intentions:write` on the resource. Intention ACL rules are specified as part of a `service` rule. See [Intention -Management Permissions](/docs/connect/intentions#intention-management-permissions) for +Management Permissions](/consul/docs/connect/intentions#intention-management-permissions) for more details. ## Regular Expression Syntax @@ -734,5 +734,5 @@ more details. The actual syntax of the regular expression fields described here is entirely proxy-specific. -When using [Envoy](/docs/connect/proxies/envoy) as a proxy, the syntax for +When using [Envoy](/consul/docs/connect/proxies/envoy) as a proxy, the syntax for these fields is [RE2](https://github.com/google/re2/wiki/Syntax). diff --git a/website/content/docs/connect/config-entries/service-resolver.mdx b/website/content/docs/connect/config-entries/service-resolver.mdx index 782d17f77e..8009db9714 100644 --- a/website/content/docs/connect/config-entries/service-resolver.mdx +++ b/website/content/docs/connect/config-entries/service-resolver.mdx @@ -20,7 +20,7 @@ and discovery terminates. ## Interaction with other Config Entries - Service resolver config entries are a component of [L7 Traffic - Management](/docs/connect/l7-traffic). + Management](/consul/docs/connect/l7-traffic). ## UI @@ -789,7 +789,7 @@ referenced by their names throughout the other configuration entry kinds. ## ACLs -Configuration entries may be protected by [ACLs](/docs/security/acl). +Configuration entries may be protected by [ACLs](/consul/docs/security/acl). Reading a `service-resolver` config entry requires `service:read` on the resource. diff --git a/website/content/docs/connect/config-entries/service-router.mdx b/website/content/docs/connect/config-entries/service-router.mdx index 10ae80c3c1..3e01850e8a 100644 --- a/website/content/docs/connect/config-entries/service-router.mdx +++ b/website/content/docs/connect/config-entries/service-router.mdx @@ -16,26 +16,26 @@ service of the same name. ## Requirements -- Consul [service mesh connect](/docs/connect/configuration) enabled services +- Consul [service mesh connect](/consul/docs/connect/configuration) enabled services - Service to service communication over the protocol `http` ## Interaction with other Config Entries - Service router config entries are a component of [L7 Traffic - Management](/docs/connect/l7-traffic). + Management](/consul/docs/connect/l7-traffic). - Service router config entries are restricted to only services that define their protocol as HTTP-based via a corresponding - [`service-defaults`](/docs/connect/config-entries/service-defaults) config + [`service-defaults`](/consul/docs/connect/config-entries/service-defaults) config entry or globally via - [`proxy-defaults`](/docs/connect/config-entries/proxy-defaults) . + [`proxy-defaults`](/consul/docs/connect/config-entries/proxy-defaults) . - Any route destination that omits the `ServiceSubset` field is eligible for splitting via a - [`service-splitter`](/docs/connect/config-entries/service-splitter) should + [`service-splitter`](/consul/docs/connect/config-entries/service-splitter) should one be configured for that service, otherwise resolution proceeds according to any configured - [`service-resolver`](/docs/connect/config-entries/service-resolver). + [`service-resolver`](/consul/docs/connect/config-entries/service-resolver). ## UI @@ -778,7 +778,7 @@ spec: ## ACLs -Configuration entries may be protected by [ACLs](/docs/security/acl). +Configuration entries may be protected by [ACLs](/consul/docs/security/acl). Reading a `service-router` config entry requires `service:read` on the resource. @@ -793,7 +793,7 @@ name in these fields: The actual syntax of the regular expression fields described here is entirely proxy-specific. -When using [Envoy](/docs/connect/proxies/envoy) as a proxy (the only supported proxy in Kubernetes), +When using [Envoy](/consul/docs/connect/proxies/envoy) as a proxy (the only supported proxy in Kubernetes), the syntax for these fields is version specific: | Envoy Version | Syntax | diff --git a/website/content/docs/connect/config-entries/service-splitter.mdx b/website/content/docs/connect/config-entries/service-splitter.mdx index c9271fb5c1..4386fba281 100644 --- a/website/content/docs/connect/config-entries/service-splitter.mdx +++ b/website/content/docs/connect/config-entries/service-splitter.mdx @@ -22,19 +22,19 @@ resolution stage. ## Interaction with other Config Entries - Service splitter config entries are a component of [L7 Traffic - Management](/docs/connect/l7-traffic). + Management](/consul/docs/connect/l7-traffic). - Service splitter config entries are restricted to only services that define their protocol as http-based via a corresponding - [`service-defaults`](/docs/connect/config-entries/service-defaults) config + [`service-defaults`](/consul/docs/connect/config-entries/service-defaults) config entry or globally via - [`proxy-defaults`](/docs/connect/config-entries/proxy-defaults) . + [`proxy-defaults`](/consul/docs/connect/config-entries/proxy-defaults) . - Any split destination that specifies a different `Service` field and omits the `ServiceSubset` field is eligible for further splitting should a splitter be configured for that other service, otherwise resolution proceeds according to any configured - [`service-resolver`](/docs/connect/config-entries/service-resolver). + [`service-resolver`](/consul/docs/connect/config-entries/service-resolver). ## UI @@ -351,7 +351,7 @@ spec: ## ACLs -Configuration entries may be protected by [ACLs](/docs/security/acl). +Configuration entries may be protected by [ACLs](/consul/docs/security/acl). Reading a `service-splitter` config entry requires `service:read` on the resource. diff --git a/website/content/docs/connect/config-entries/terminating-gateway.mdx b/website/content/docs/connect/config-entries/terminating-gateway.mdx index 3339d174bc..b7e0f38b7c 100644 --- a/website/content/docs/connect/config-entries/terminating-gateway.mdx +++ b/website/content/docs/connect/config-entries/terminating-gateway.mdx @@ -12,21 +12,21 @@ description: >- The `terminating-gateway` config entry kind (`TerminatingGateway` on Kubernetes) allows you to configure terminating gateways to proxy traffic from services in the Consul service mesh to services registered with Consul that do not have a -[Connect service sidecar proxy](/docs/connect/proxies). The configuration is associated with the name of a gateway service +[Connect service sidecar proxy](/consul/docs/connect/proxies). The configuration is associated with the name of a gateway service and will apply to all instances of the gateway with that name. -~> [Configuration entries](/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies +~> [Configuration entries](/consul/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies across all federated Consul datacenters. If terminating gateways in different Consul datacenters need to route to different sets of services within their datacenter then the terminating gateways **must** be registered with different names. -See [Terminating Gateway](/docs/connect/gateways/terminating-gateway) for more information. +See [Terminating Gateway](/consul/docs/connect/gateways/terminating-gateway) for more information. ## TLS Origination -By specifying a path to a [CA file](/docs/connect/config-entries/terminating-gateway#cafile) connections +By specifying a path to a [CA file](/consul/docs/connect/config-entries/terminating-gateway#cafile) connections from the terminating gateway will be encrypted using one-way TLS authentication. If a path to a -[client certificate](/docs/connect/config-entries/terminating-gateway#certfile) -and [private key](/docs/connect/config-entries/terminating-gateway#keyfile) are also specified connections +[client certificate](/consul/docs/connect/config-entries/terminating-gateway#certfile) +and [private key](/consul/docs/connect/config-entries/terminating-gateway#keyfile) are also specified connections from the terminating gateway will be encrypted using mutual TLS authentication. ~> Setting the `SNI` field is strongly recommended when enabling TLS to a service. If this field is not set, @@ -154,7 +154,7 @@ file to be used for one-way TLS authentication. -> **Note**: When not using destinations in transparent proxy mode, you must specify the `CAFile` parameter and point to a valid CA bundle in order to properly initiate a TLS -connection to the destination service. For more information about configuring a gateway for destinations, refer to [Register an External Service as a Destination](/docs/k8s/connect/terminating-gateways#register-an-external-service-as-a-destination). +connection to the destination service. For more information about configuring a gateway for destinations, refer to [Register an External Service as a Destination](/consul/docs/k8s/connect/terminating-gateways#register-an-external-service-as-a-destination). @@ -689,7 +689,7 @@ spec: ## ACLs -Configuration entries may be protected by [ACLs](/docs/security/acl). +Configuration entries may be protected by [ACLs](/consul/docs/security/acl). Reading a `terminating-gateway` config entry requires `service:read` on the `Name` field of the config entry. diff --git a/website/content/docs/connect/configuration.mdx b/website/content/docs/connect/configuration.mdx index 998bb5a0dd..8fbd88fa32 100644 --- a/website/content/docs/connect/configuration.mdx +++ b/website/content/docs/connect/configuration.mdx @@ -22,7 +22,7 @@ Begin by enabling Connect for your Consul cluster. By default, Connect is disabled. Enabling Connect requires changing the configuration of only your Consul _servers_ (not client agents). To enable Connect, add the following to a new or existing -[server configuration file](/docs/agent/config/config-files). In an existing cluster, this configuration change requires a Consul server restart, which you can perform one server at a time to maintain availability. In HCL: +[server configuration file](/consul/docs/agent/config/config-files). In an existing cluster, this configuration change requires a Consul server restart, which you can perform one server at a time to maintain availability. In HCL: @@ -43,7 +43,7 @@ connect { This will enable Connect and configure your Consul cluster to use the built-in certificate authority for creating and managing certificates. You may also configure Consul to use an external -[certificate management system](/docs/connect/ca), such as +[certificate management system](/consul/docs/connect/ca), such as [Vault](https://www.vaultproject.io/). Services and proxies may always register with Connect settings, but they will @@ -53,26 +53,26 @@ connection attempts to fail until Connect is enabled on the server agents. Other optional Connect configurations that you can set in the server configuration file include: -- [certificate authority settings](/docs/agent/config/config-files#connect) -- [token replication](/docs/agent/config/config-files#acl_tokens_replication) -- [dev mode](/docs/agent/config/cli-flags#_dev) -- [server host name verification](/docs/agent/config/config-files#tls_internal_rpc_verify_server_hostname) +- [certificate authority settings](/consul/docs/agent/config/config-files#connect) +- [token replication](/consul/docs/agent/config/config-files#acl_tokens_replication) +- [dev mode](/consul/docs/agent/config/cli-flags#_dev) +- [server host name verification](/consul/docs/agent/config/config-files#tls_internal_rpc_verify_server_hostname) If you would like to use Envoy as your Connect proxy you will need to [enable -gRPC](/docs/agent/config/config-files#grpc_port). +gRPC](/consul/docs/agent/config/config-files#grpc_port). Additionally if you plan on using the observability features of Connect, it can be convenient to configure your proxies and services using [configuration -entries](/docs/agent/config-entries) which you can interact with using the +entries](/consul/docs/agent/config-entries) which you can interact with using the CLI or API, or by creating configuration entry files. You will want to enable [centralized service -configuration](/docs/agent/config/config-files#enable_central_service_config) on +configuration](/consul/docs/agent/config/config-files#enable_central_service_config) on clients, which allows each service's proxy configuration to be managed centrally via API. !> **Security note:** Enabling Connect is enough to try the feature but doesn't automatically ensure complete security. Please read the [Connect production -tutorial](https://learn.hashicorp.com/tutorials/consul/service-mesh-production-checklist) to understand the additional steps +tutorial](/consul/tutorials/developer-mesh/service-mesh-production-checklist) to understand the additional steps needed for a secure deployment. ## Centralized Proxy and Service Configuration @@ -80,13 +80,13 @@ needed for a secure deployment. To account for common Connect use cases where you have many instances of the same service, and many colocated sidecar proxies, Consul allows you to customize the settings for all of your proxies or all the instances of a given service at -once using [Configuration Entries](/docs/agent/config-entries). +once using [Configuration Entries](/consul/docs/agent/config-entries). You can override centralized configurations for individual proxy instances in their -[sidecar service definitions](/docs/connect/registration/sidecar-service), +[sidecar service definitions](/consul/docs/connect/registration/sidecar-service), and the default protocols for service instances in their [service -registrations](/docs/discovery/services). +registrations](/consul/docs/discovery/services). ## Schedulers @@ -102,12 +102,12 @@ Connect can be used with Nomad to provide secure service-to-service communication between Nomad jobs and task groups. The ability to use the dynamic port feature of Nomad makes Connect particularly easy to use. Learn about how to configure Connect on Nomad by reading the -[integration documentation](/docs/connect/nomad). +[integration documentation](/consul/docs/connect/nomad). ### Kubernetes The Consul Helm chart can automate much of Consul Connect's configuration, and makes it easy to automatically inject Envoy sidecars into new pods when they are -deployed. Learn about the [Helm chart](/docs/k8s/helm) in general, +deployed. Learn about the [Helm chart](/consul/docs/k8s/helm) in general, or if you are already familiar with it, check out its -[connect specific configurations](/docs/k8s/connect). +[connect specific configurations](/consul/docs/k8s/connect). diff --git a/website/content/docs/connect/connect-internals.mdx b/website/content/docs/connect/connect-internals.mdx index 51c3806383..db5a0d1636 100644 --- a/website/content/docs/connect/connect-internals.mdx +++ b/website/content/docs/connect/connect-internals.mdx @@ -14,7 +14,7 @@ but this information will help you understand how Consul service mesh behaves in Consul Connect is the component shipped with Consul that enables service mesh functionality. The terms _Consul Connect_ and _Consul service mesh_ are used interchangeably throughout this documentation. To try service mesh locally, complete the [Getting Started with Consul service -mesh](https://learn.hashicorp.com/tutorials/consul/service-mesh?utm_source=docs) +mesh](/consul/tutorials/kubernetes-deploy/service-mesh?utm_source=docs) tutorial. ## Mutual Transport Layer Security (mTLS) @@ -29,17 +29,17 @@ This enables Connect services to establish and accept connections with other SPIFFE-compliant systems. The client service verifies the destination service certificate -against the [public CA bundle](/api-docs/connect/ca#list-ca-root-certificates). +against the [public CA bundle](/consul/api-docs/connect/ca#list-ca-root-certificates). This is very similar to a typical HTTPS web browser connection. In addition to this, the client provides its own client certificate to show its identity to the destination service. If the connection handshake succeeds, the connection is encrypted and authorized. The destination service verifies the client certificate against the [public CA -bundle](/api-docs/connect/ca#list-ca-root-certificates). After verifying the +bundle](/consul/api-docs/connect/ca#list-ca-root-certificates). After verifying the certificate, the next step depends upon the configured application protocol of the destination service. TCP (L4) services must authorize incoming _connections_ -against the configured set of Consul [intentions](/docs/connect/intentions), +against the configured set of Consul [intentions](/consul/docs/connect/intentions), whereas HTTP (L7) services must authorize incoming _requests_ against those same intentions. If the intention check responds successfully, the connection/request is established. Otherwise the connection/request is @@ -47,21 +47,21 @@ rejected. To generate and distribute certificates, Consul has a built-in CA that requires no other dependencies, and -also ships with built-in support for [Vault](/docs/connect/ca/vault). The PKI system is designed to be pluggable +also ships with built-in support for [Vault](/consul/docs/connect/ca/vault). The PKI system is designed to be pluggable and can be extended to support any system by adding additional CA providers. All APIs required for Connect typically respond in microseconds and impose minimal overhead to existing services. To ensure this, Connect-related API calls are all made to the local Consul agent over a loopback interface, and all [agent -Connect endpoints](/api-docs/agent/connect) implement local caching, background +Connect endpoints](/consul/api-docs/agent/connect) implement local caching, background updating, and support blocking queries. Most API calls operate on purely local in-memory data. ## Agent Caching and Performance To enable fast responses on endpoints such as the [agent Connect -API](/api-docs/agent/connect), the Consul agent locally caches most Connect-related -data and sets up background [blocking queries](/api-docs/features/blocking) against +API](/consul/api-docs/agent/connect), the Consul agent locally caches most Connect-related +data and sets up background [blocking queries](/consul/api-docs/features/blocking) against the server to update the cache in the background. This allows most API calls such as retrieving certificates or authorizing connections to use in-memory data and respond very quickly. @@ -94,11 +94,11 @@ a long period of inactivity (3 days by default), the cache will empty itself. ## Connections Across Datacenters -A sidecar proxy's [upstream configuration](/docs/connect/registration/service-registration#upstream-configuration-reference) +A sidecar proxy's [upstream configuration](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) may specify an alternative datacenter or a prepared query that can address services -in multiple datacenters (such as the [geo failover](https://learn.hashicorp.com/tutorials/consul/automate-geo-failover) pattern). +in multiple datacenters (such as the [geo failover](/consul/tutorials/developer-discovery/automate-geo-failover) pattern). -[Intentions](/docs/connect/intentions) verify connections between services by +[Intentions](/consul/docs/connect/intentions) verify connections between services by source and destination name seamlessly across datacenters. Connections can be made via gateways to enable communicating across network @@ -108,10 +108,10 @@ externally routable IPs at the service level. ## Intention Replication Intention replication happens automatically but requires the -[`primary_datacenter`](/docs/agent/config/config-files#primary_datacenter) +[`primary_datacenter`](/consul/docs/agent/config/config-files#primary_datacenter) configuration to be set to specify a datacenter that is authoritative for intentions. In production setups with ACLs enabled, the -[replication token](/docs/agent/config/config-files#acl_tokens_replication) must also +[replication token](/consul/docs/agent/config/config-files#acl_tokens_replication) must also be set in the secondary datacenter server's configuration. ## Certificate Authority Federation diff --git a/website/content/docs/connect/connectivity-tasks.mdx b/website/content/docs/connect/connectivity-tasks.mdx index deb4ef0b7c..c81c0ebda5 100644 --- a/website/content/docs/connect/connectivity-tasks.mdx +++ b/website/content/docs/connect/connectivity-tasks.mdx @@ -22,13 +22,13 @@ These gateways operate by sniffing the SNI header out of the mTLS connection and appropriate destination based on the server name requested. As of Consul 1.8.0, mesh gateways can also forward gossip and RPC traffic between Consul servers. -This is enabled by [WAN federation via mesh gateways](/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways). +This is enabled by [WAN federation via mesh gateways](/consul/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways). As of Consul 1.14.0, mesh gateways can route both data-plane (service-to-service) and control-plane (consul-to-consul) traffic for peered clusters. -See [Mesh Gateways for Peering Control Plane Traffic](/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways) +See [Mesh Gateways for Peering Control Plane Traffic](/consul/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways) -For more information about mesh gateways, review the [complete documentation](/docs/connect/gateways/mesh-gateway) -and the [mesh gateway tutorial](https://learn.hashicorp.com/tutorials/consul/service-mesh-gateways). +For more information about mesh gateways, review the [complete documentation](/consul/docs/connect/gateways/mesh-gateway) +and the [mesh gateway tutorial](/consul/tutorials/developer-mesh/service-mesh-gateways). ![Mesh Gateway Architecture](/img/mesh-gateways.png) @@ -45,8 +45,8 @@ an ingress gateway by defining a set of listeners that can map to different sets Ingress gateways are tightly integrated with Consul's L7 configuration and enable dynamic routing of HTTP requests by attributes like the request path. -For more information about ingress gateways, review the [complete documentation](/docs/connect/gateways/ingress-gateway) -and the [ingress gateway tutorial](https://learn.hashicorp.com/tutorials/consul/service-mesh-gateways). +For more information about ingress gateways, review the [complete documentation](/consul/docs/connect/gateways/ingress-gateway) +and the [ingress gateway tutorial](/consul/tutorials/developer-mesh/service-mesh-gateways). ![Ingress Gateway Architecture](/img/ingress-gateways.png) @@ -55,7 +55,7 @@ and the [ingress gateway tutorial](https://learn.hashicorp.com/tutorials/consul/ -> **1.8.0+:** This feature is available in Consul versions 1.8.0 and newer. Terminating gateways enable connectivity from services in the Consul service mesh to services outside the mesh. -Services outside the mesh do not have sidecar proxies or are not [integrated natively](/docs/connect/native). +Services outside the mesh do not have sidecar proxies or are not [integrated natively](/consul/docs/connect/native). These may be services running on legacy infrastructure or managed cloud services running on infrastructure you do not control. @@ -66,7 +66,7 @@ These gateways also simplify authorization from dynamic service addresses. Consu connections through the gateway are authorized. Then traditional tools like firewalls or IAM roles can authorize the connections from the known gateway nodes to the destination services. -For more information about terminating gateways, review the [complete documentation](/docs/connect/gateways/terminating-gateway) -and the [terminating gateway tutorial](https://learn.hashicorp.com/tutorials/consul/terminating-gateways-connect-external-services). +For more information about terminating gateways, review the [complete documentation](/consul/docs/connect/gateways/terminating-gateway) +and the [terminating gateway tutorial](/consul/tutorials/developer-mesh/terminating-gateways-connect-external-services). ![Terminating Gateway Architecture](/img/terminating-gateways.png) diff --git a/website/content/docs/connect/dataplane/consul-dataplane.mdx b/website/content/docs/connect/dataplane/consul-dataplane.mdx index 66069f9bbb..b4661d8612 100644 --- a/website/content/docs/connect/dataplane/consul-dataplane.mdx +++ b/website/content/docs/connect/dataplane/consul-dataplane.mdx @@ -76,7 +76,7 @@ The following options are required when starting `consul-dataplane` with the CLI - `-telemetry-prom-cert-file` - The path to the client certificate used to serve Prometheus metrics. Accepted environment variable is `DP_TELEMETRY_PROM_CERT_FILE`. - `-telemetry-prom-key-file` - The path to the client private key used to serve Prometheus metrics. Accepted environment variable is `DP_TELEMETRY_PROM_KEY_FILE`. - `-telemetry-prom-merge-port` - The local port used to serve merged Prometheus metrics. Default is `20100`. If your service instance uses the same default port, this flag must be set to a different port in order to avoid a port conflict. Accepted environment variable is `DP_TELEMETRY_PROM_MERGE_PORT`. -- `-telemetry-prom-retention-time` - The duration for Prometheus metrics aggregation. Default is `1m0s`. Accepted environment variable is `DP_TELEMETRY_PROM_RETENTION_TIME`. Refer to [`prometheus_retention_time`](/docs/agent/config/config-files#telemetry-prometheus_retention_time) for details on setting this value. +- `-telemetry-prom-retention-time` - The duration for Prometheus metrics aggregation. Default is `1m0s`. Accepted environment variable is `DP_TELEMETRY_PROM_RETENTION_TIME`. Refer to [`prometheus_retention_time`](/consul/docs/agent/config/config-files#telemetry-prometheus_retention_time) for details on setting this value. - `-telemetry-prom-scrape-path` - The URL path where Envoy serves Prometheus metrics. Default is `"/metrics"`. Accepted environment variable is `DP_TELEMETRY_PROM_SCRAPE_PATH`. - `-telemetry-prom-service-metrics-url` - The URL where your service instance serves Prometheus metrics. If this is set, the metrics at this URL are included in Consul Dataplane's merged Prometheus metrics. Accepted environment variable is `DP_TELEMETRY_PROM_SERVICE_METRICS_URL`. - `-telemetry-use-central-config` - Controls whether the proxy applies the central telemetry configuration. Default is `true`. Accepted environment variable is `DP_TELEMETRY_USE_CENTRAL_CONFIG`. diff --git a/website/content/docs/connect/dataplane/index.mdx b/website/content/docs/connect/dataplane/index.mdx index df6fb0de6c..fea7c7fd67 100644 --- a/website/content/docs/connect/dataplane/index.mdx +++ b/website/content/docs/connect/dataplane/index.mdx @@ -45,13 +45,13 @@ As a result, small deployments require fewer resources overall. For deployments To get started with Consul Dataplane, use the following reference resources: -- For `consul-dataplane` commands and usage examples, including required flags for startup, refer to the [`consul-dataplane` CLI reference](/docs/connect/dataplane/consul-dataplane). -- For Helm chart information, refer to the [Helm Chart reference](/docs/k8s/helm). -- For Envoy, Consul, and Consul Dataplane version compatibility, refer to the [Envoy compatibility matrix](/docs/connect/proxies/envoy). +- For `consul-dataplane` commands and usage examples, including required flags for startup, refer to the [`consul-dataplane` CLI reference](/consul/docs/connect/dataplane/consul-dataplane). +- For Helm chart information, refer to the [Helm Chart reference](/consul/docs/k8s/helm). +- For Envoy, Consul, and Consul Dataplane version compatibility, refer to the [Envoy compatibility matrix](/consul/docs/connect/proxies/envoy). ### Installation -To install Consul Dataplane, set `VERSION` to `1.0.0` and then follow the instructions to install a specific version of Consul [with the Helm Chart](/docs/k8s/installation/install#install-consul) or [with the Consul-k8s CLI](/docs/k8s/installation/install-cli#install-a-previous-version). +To install Consul Dataplane, set `VERSION` to `1.0.0` and then follow the instructions to install a specific version of Consul [with the Helm Chart](/consul/docs/k8s/installation/install#install-consul) or [with the Consul-k8s CLI](/consul/docs/k8s/installation/install-cli#install-a-previous-version). #### Helm @@ -69,7 +69,7 @@ $ export VERSION=1.0.0 && \ ### Upgrading -Before you upgrade Consul to a version that uses Consul Dataplane, you must edit your Helm chart so that client agents are removed from your deployments. Refer to [upgrading to Consul Dataplane](/docs/k8s/upgrade#upgrading-to-consul-dataplanes) for more information. +Before you upgrade Consul to a version that uses Consul Dataplane, you must edit your Helm chart so that client agents are removed from your deployments. Refer to [upgrading to Consul Dataplane](/consul/docs/k8s/upgrade#upgrading-to-consul-dataplanes) for more information. ## Feature support diff --git a/website/content/docs/connect/dataplane/telemetry.mdx b/website/content/docs/connect/dataplane/telemetry.mdx index e9de1e3a5d..ce111e4872 100644 --- a/website/content/docs/connect/dataplane/telemetry.mdx +++ b/website/content/docs/connect/dataplane/telemetry.mdx @@ -18,7 +18,7 @@ Consul Dataplane uses the same external metrics store that is configured for Env telemetry for Consul Dataplane, enable telemetry for Envoy by specifying an external metrics store in the proxy-defaults configuration entry or directly in the proxy.config field of the proxy service definition. Refer to the [Envoy bootstrap -configuration](/docs/connect/proxies/envoy#bootstrap-configuration) for details. +configuration](/consul/docs/connect/proxies/envoy#bootstrap-configuration) for details. ## Prometheus Metrics Merging diff --git a/website/content/docs/connect/dev.mdx b/website/content/docs/connect/dev.mdx index a4d900afa8..6f494bc375 100644 --- a/website/content/docs/connect/dev.mdx +++ b/website/content/docs/connect/dev.mdx @@ -10,12 +10,12 @@ description: >- It is often necessary to connect to a service for development or debugging. If a service only exposes a Connect listener, then we need a way to establish a mutual TLS connection to the service. The -[`consul connect proxy` command](/commands/connect/proxy) can be used +[`consul connect proxy` command](/consul/commands/connect/proxy) can be used for this task on any machine with access to a Consul agent (local or remote). Restricting access to services only via Connect ensures that the only way to connect to a service is through valid authorization of the -[intentions](/docs/connect/intentions). This can extend to developers +[intentions](/consul/docs/connect/intentions). This can extend to developers and operators, too. ## Connecting to Connect-only Services diff --git a/website/content/docs/connect/distributed-tracing.mdx b/website/content/docs/connect/distributed-tracing.mdx index 9c177b82dd..1c601ec27f 100644 --- a/website/content/docs/connect/distributed-tracing.mdx +++ b/website/content/docs/connect/distributed-tracing.mdx @@ -145,16 +145,16 @@ spec: --> **NOTE:** This example uses a [proxy defaults](/docs/connect/config-entries/proxy-defaults) config entry which will apply to all proxies +-> **NOTE:** This example uses a [proxy defaults](/consul/docs/connect/config-entries/proxy-defaults) config entry which will apply to all proxies but you can also apply this config in the -[proxy service registration](/docs/connect/registration/service-registration#proxy-parameters) (not supported on Kubernetes). +[proxy service registration](/consul/docs/connect/registration/service-registration#proxy-parameters) (not supported on Kubernetes). Within the config there are two keys you need to customize: -1. [`envoy_tracing_json`](/docs/connect/proxies/envoy#envoy_tracing_json): Sets the tracing configuration for your specific tracing type. +1. [`envoy_tracing_json`](/consul/docs/connect/proxies/envoy#envoy_tracing_json): Sets the tracing configuration for your specific tracing type. See the [Envoy tracers documentation](https://www.envoyproxy.io/docs/envoy/latest/api-v3/config/trace/trace) for your specific collector's configuration. This configuration will reference the cluster name defined in `envoy_extra_static_clusters_json`. -1. [`envoy_extra_static_clusters_json`](/docs/connect/proxies/envoy#envoy_extra_static_clusters_json): Defines the address +1. [`envoy_extra_static_clusters_json`](/consul/docs/connect/proxies/envoy#envoy_extra_static_clusters_json): Defines the address of your tracing collector where Envoy will send its spans. In this example the URL was `collector-url:9411`. ## Applying the configuration @@ -231,7 +231,7 @@ config to take effect. -1. Requests through [Ingress Gateways](/docs/connect/gateways/ingress-gateway) will not be traced unless the header +1. Requests through [Ingress Gateways](/consul/docs/connect/gateways/ingress-gateway) will not be traced unless the header `x-client-trace-id: 1` is set (see [hashicorp/consul#6645](https://github.com/hashicorp/consul/issues/6645)). 1. Consul does not currently support interoperation with [OpenTelemetry](https://opentelemetry.io/) libraries due to diff --git a/website/content/docs/connect/gateways/index.mdx b/website/content/docs/connect/gateways/index.mdx index 6afe42144d..fb04a9e549 100644 --- a/website/content/docs/connect/gateways/index.mdx +++ b/website/content/docs/connect/gateways/index.mdx @@ -27,13 +27,13 @@ They operate by sniffing and extracting the server name indication (SNI) header Mesh gateways enable the following scenarios: -* **Federate multiple datacenters across a WAN**. Since Consul 1.8.0, mesh gateways can forward gossip and RPC traffic between Consul servers. See [WAN federation via mesh gateways](/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways) for additional information. -- **Service-to-service communication across WAN-federated datacenters**. Refer to [Enabling Service-to-service Traffic Across Datacenters](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters) for additional information. -- **Service-to-service communication across admin partitions**. Since Consul 1.11.0, you can create administrative boundaries for single Consul deployments called "admin partitions". You can use mesh gateways to facilitate cross-partition communication. Refer to [Enabling Service-to-service Traffic Across Admin Partitions](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions) for additional information. -- **Bridge multiple datacenters using Cluster Peering**. Since Consul 1.14.0, mesh gateways can be used to route peering control-plane traffic between peered Consul Servers. See [Mesh Gateways for Peering Control Plane Traffic](/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways) for more information. -- **Service-to-service communication across peered datacenters**. Refer to [Mesh Gateways between Peered Clusters](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers) for more information. +* **Federate multiple datacenters across a WAN**. Since Consul 1.8.0, mesh gateways can forward gossip and RPC traffic between Consul servers. See [WAN federation via mesh gateways](/consul/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways) for additional information. +- **Service-to-service communication across WAN-federated datacenters**. Refer to [Enabling Service-to-service Traffic Across Datacenters](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters) for additional information. +- **Service-to-service communication across admin partitions**. Since Consul 1.11.0, you can create administrative boundaries for single Consul deployments called "admin partitions". You can use mesh gateways to facilitate cross-partition communication. Refer to [Enabling Service-to-service Traffic Across Admin Partitions](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions) for additional information. +- **Bridge multiple datacenters using Cluster Peering**. Since Consul 1.14.0, mesh gateways can be used to route peering control-plane traffic between peered Consul Servers. See [Mesh Gateways for Peering Control Plane Traffic](/consul/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways) for more information. +- **Service-to-service communication across peered datacenters**. Refer to [Mesh Gateways between Peered Clusters](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers) for more information. --> **Mesh gateway tutorial**: Follow the [mesh gateway tutorial](https://learn.hashicorp.com/tutorials/consul/service-mesh-gateways) to learn concepts associated with mesh gateways. +-> **Mesh gateway tutorial**: Follow the [mesh gateway tutorial](/consul/tutorials/developer-mesh/service-mesh-gateways) to learn concepts associated with mesh gateways. ## Ingress Gateways @@ -49,8 +49,8 @@ an ingress gateway by defining a set of listeners that can map to different sets Ingress gateways are tightly integrated with Consul's L7 configuration and enable dynamic routing of HTTP requests by attributes like the request path. -For more information about ingress gateways, review the [complete documentation](/docs/connect/gateways/ingress-gateway) -and the [ingress gateway tutorial](https://learn.hashicorp.com/tutorials/consul/service-mesh-ingress-gateways). +For more information about ingress gateways, review the [complete documentation](/consul/docs/connect/gateways/ingress-gateway) +and the [ingress gateway tutorial](/consul/tutorials/developer-mesh/service-mesh-ingress-gateways). ![Ingress Gateway Architecture](/img/ingress-gateways.png) @@ -60,7 +60,7 @@ and the [ingress gateway tutorial](https://learn.hashicorp.com/tutorials/consul/ Terminating gateways enable connectivity within your organizational network from services in the Consul service mesh to services outside the mesh. -Services outside the mesh do not have sidecar proxies or are not [integrated natively](/docs/connect/native). +Services outside the mesh do not have sidecar proxies or are not [integrated natively](/consul/docs/connect/native). These may be services running on legacy infrastructure or managed cloud services running on infrastructure you do not control. @@ -71,7 +71,7 @@ These gateways also simplify authorization from dynamic service addresses. Consu connections through the gateway are authorized. Then traditional tools like firewalls or IAM roles can authorize the connections from the known gateway nodes to the destination services. -For more information about terminating gateways, review the [complete documentation](/docs/connect/gateways/terminating-gateway) -and the [terminating gateway tutorial](https://learn.hashicorp.com/tutorials/consul/terminating-gateways-connect-external-services). +For more information about terminating gateways, review the [complete documentation](/consul/docs/connect/gateways/terminating-gateway) +and the [terminating gateway tutorial](/consul/tutorials/developer-mesh/terminating-gateways-connect-external-services). ![Terminating Gateway Architecture](/img/terminating-gateways.png) diff --git a/website/content/docs/connect/gateways/ingress-gateway.mdx b/website/content/docs/connect/gateways/ingress-gateway.mdx index 8a30a1e34b..d75dbd5ebc 100644 --- a/website/content/docs/connect/gateways/ingress-gateway.mdx +++ b/website/content/docs/connect/gateways/ingress-gateway.mdx @@ -12,25 +12,25 @@ description: >- Ingress gateways enable connectivity within your organizational network from services outside the Consul service mesh to services in the mesh. An ingress gateway is a type of proxy and must be registered as a service in Consul, with the -[kind](/api-docs/agent/service#kind) set to "ingress-gateway". They are an +[kind](/consul/api-docs/agent/service#kind) set to "ingress-gateway". They are an entrypoint for outside traffic and allow you to define what services should be exposed and on what port. You configure an ingress gateway by defining a set of -[listeners](/docs/connect/config-entries/ingress-gateway#listeners) that each map +[listeners](/consul/docs/connect/config-entries/ingress-gateway#listeners) that each map to a set of backing -[services](/docs/connect/config-entries/ingress-gateway#services). +[services](/consul/docs/connect/config-entries/ingress-gateway#services). To enable easier service discovery, a new Consul [DNS -subdomain](/docs/discovery/dns#ingress-service-lookups) is provided, on +subdomain](/consul/docs/discovery/dns#ingress-service-lookups) is provided, on `.ingress.`. For listeners with a -[protocol](/docs/connect/config-entries/ingress-gateway#protocol) other than +[protocol](/consul/docs/connect/config-entries/ingress-gateway#protocol) other than `tcp`, multiple services can be specified for a single listener. In this case, the ingress gateway relies on host/authority headers to decide the service that should receive the traffic. The host used to match traffic defaults to the [Consul DNS ingress -subdomain](/docs/discovery/dns#ingress-service-lookups), but can be changed using -the [hosts](/docs/connect/config-entries/ingress-gateway#hosts) field. +subdomain](/consul/docs/discovery/dns#ingress-service-lookups), but can be changed using +the [hosts](/consul/docs/connect/config-entries/ingress-gateway#hosts) field. ![Ingress Gateway Architecture](/img/ingress-gateways.png) @@ -39,24 +39,24 @@ the [hosts](/docs/connect/config-entries/ingress-gateway#hosts) field. Ingress gateways also require that your Consul datacenters are configured correctly: - You'll need to use Consul version 1.8.0 or newer. -- Consul [Connect](/docs/agent/config/config-files#connect) must be enabled on the datacenter's Consul servers. -- [gRPC](/docs/agent/config/config-files#grpc_port) must be enabled on all client agents. +- Consul [Connect](/consul/docs/agent/config/config-files#connect) must be enabled on the datacenter's Consul servers. +- [gRPC](/consul/docs/agent/config/config-files#grpc_port) must be enabled on all client agents. Currently, [Envoy](https://www.envoyproxy.io/) is the only proxy with ingress gateway capabilities in Consul. ## Running and Using an Ingress Gateway For a complete example of how to allow external traffic inside your Consul service mesh, -review the [ingress gateway tutorial](https://learn.hashicorp.com/tutorials/consul/service-mesh-ingress-gateways). +review the [ingress gateway tutorial](/consul/tutorials/developer-mesh/service-mesh-ingress-gateways). ## Ingress Gateway Configuration Ingress gateways are configured in service definitions and registered with Consul like other services, with two exceptions. -The first is that the [kind](/api-docs/agent/service#kind) must be "ingress-gateway". Second, +The first is that the [kind](/consul/api-docs/agent/service#kind) must be "ingress-gateway". Second, the ingress gateway service definition may contain a `Proxy.Config` entry just like a Connect proxy service, to define opaque configuration parameters useful for the actual proxy software. -For Envoy there are some supported [gateway options](/docs/connect/proxies/envoy#gateway-options) as well as -[escape-hatch overrides](/docs/connect/proxies/envoy#escape-hatch-overrides). +For Envoy there are some supported [gateway options](/consul/docs/connect/proxies/envoy#gateway-options) as well as +[escape-hatch overrides](/consul/docs/connect/proxies/envoy#escape-hatch-overrides). -> **Note:** If ACLs are enabled, ingress gateways must be registered with a token granting `service:write` for the ingress gateway's service name, `service:read` for all services in the ingress gateway's configuration entry, and `node:read` for all nodes of the services @@ -64,7 +64,7 @@ in the ingress gateway's configuration entry. These privileges authorize the tok If the Consul client agent on the gateway's node is not configured to use the default gRPC port, 8502, then the gateway's token must also provide `agent:read` for its node's name in order to discover the agent's gRPC port. gRPC is used to expose Envoy's xDS API to Envoy proxies. -~> [Configuration entries](/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies +~> [Configuration entries](/consul/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies across all federated Consul datacenters. If ingress gateways in different Consul datacenters need to route to different sets of services within their datacenter, then the ingress gateways **must** be registered with different names. @@ -88,7 +88,7 @@ The following procedure describes how to configure an ingress gateway with TLS c ### Configure Static SDS Cluster(s) Each Envoy proxy that makes up this Ingress Gateway must define one or more additional [static -clusters](/docs/connect/proxies/envoy#envoy_extra_static_clusters_json) when registering. These additional clusters define how Envoy should connect to the required SDS service(s). Defining extra clusters in Envoy's bootstrap configuration requires a manual registration of the Ingress Gateway with Consul proxy. +clusters](/consul/docs/connect/proxies/envoy#envoy_extra_static_clusters_json) when registering. These additional clusters define how Envoy should connect to the required SDS service(s). Defining extra clusters in Envoy's bootstrap configuration requires a manual registration of the Ingress Gateway with Consul proxy. It's not possible to use the `-register` flag with `consul connect envoy -gateway=ingress` to automatically register the proxy in this case. The cluster(s) must provide connection information and any necessary @@ -278,4 +278,4 @@ Listeners = [ Separate certificates may be loaded per listener or per-service with hostname (SNI) switching. See the [Config Entry -reference](/docs/connect/config-entries/ingress-gateway) for more details. +reference](/consul/docs/connect/config-entries/ingress-gateway) for more details. diff --git a/website/content/docs/connect/gateways/mesh-gateway/index.mdx b/website/content/docs/connect/gateways/mesh-gateway/index.mdx index 206f724e8e..e5c5229dfc 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/index.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/index.mdx @@ -15,13 +15,13 @@ Datacenters can reside in different clouds or runtime environments where general Mesh gateways can be used with any of the following Consul configrations for managing separate datacenters or partitions. 1. WAN Federation - * [Mesh gateways can be used to route service-to-service traffic between datacenters](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters) - * [Mesh gateways can be used to route all WAN traffic, including from Consul servers](/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways) + * [Mesh gateways can be used to route service-to-service traffic between datacenters](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters) + * [Mesh gateways can be used to route all WAN traffic, including from Consul servers](/consul/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways) 2. Cluster Peering - * [Mesh gateways can be used to route service-to-service traffic between datacenters](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers) - * [Mesh gateways can be used to route control-plane traffic from Consul servers](/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways) + * [Mesh gateways can be used to route service-to-service traffic between datacenters](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers) + * [Mesh gateways can be used to route control-plane traffic from Consul servers](/consul/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways) 3. Admin Partitions - * [Mesh gateways can be used to route service-to-service traffic between admin partitions in the same Consul datacenter](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions) + * [Mesh gateways can be used to route service-to-service traffic between admin partitions in the same Consul datacenter](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions) ### Consul @@ -48,8 +48,8 @@ Sidecar proxies that do not send upstream traffic through a gateway are not affe Configure the following settings to register the mesh gateway as a service in Consul. * Specify `mesh-gateway` in the `kind` field to register the gateway with Consul. -* Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and datacenter. Refer to the [`upstreams` documentation](/docs/connect/registration/service-registration#upstream-configuration-reference) for details. The service `proxy.upstreams.destination_name` is always required. The `proxy.upstreams.datacenter` must be configured to enable cross-datacenter traffic. The `proxy.upstreams.destination_namespace` configuration is only necessary if the destination service is in a different namespace. -* Define the `Proxy.Config` settings using opaque parameters compatible with your proxy (i.e., Envoy). For Envoy, refer to the [Gateway Options](/docs/connect/proxies/envoy#gateway-options) and [Escape-hatch Overrides](/docs/connect/proxies/envoy#escape-hatch-overrides) documentation for additional configuration information. +* Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and datacenter. Refer to the [`upstreams` documentation](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) for details. The service `proxy.upstreams.destination_name` is always required. The `proxy.upstreams.datacenter` must be configured to enable cross-datacenter traffic. The `proxy.upstreams.destination_namespace` configuration is only necessary if the destination service is in a different namespace. +* Define the `Proxy.Config` settings using opaque parameters compatible with your proxy (i.e., Envoy). For Envoy, refer to the [Gateway Options](/consul/docs/connect/proxies/envoy#gateway-options) and [Escape-hatch Overrides](/consul/docs/connect/proxies/envoy#escape-hatch-overrides) documentation for additional configuration information. * If ACLs are enabled, a token granting `service:write` for the gateway's service name and `service:read` for all services in the datacenter or partition must be added to the gateway's service definition. These permissions authorize the token to route communications for other Consul service mesh services, but does not allow decrypting any of their communications. ### Modes @@ -127,7 +127,7 @@ Name: web ### Enabling Gateways for a Service Instance -The following [Proxy Service Registration](/docs/connect/registration/service-registration) +The following [Proxy Service Registration](/consul/docs/connect/registration/service-registration) definition will enable gateways for the service instance in the `remote` mode. diff --git a/website/content/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways.mdx b/website/content/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways.mdx index 6751e28bd4..e538a5bc86 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways.mdx @@ -7,7 +7,7 @@ description: >- # Enabling Peering Control Plane Traffic -In addition to [service-to-service traffic routing](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers), +In addition to [service-to-service traffic routing](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers), we recommend routing control plane traffic between cluster peers through mesh gateways to simplfy networking requirements. @@ -36,7 +36,7 @@ To configure mesh gateways for cluster peering control plane traffic, make sure - Consul version 1.14.0 or newer. - A local Consul agent in both clusters is required to manage mesh gateway configuration. -- Use [Envoy proxies](/docs/connect/proxies/envoy). Envoy is the only proxy with mesh gateway capabilities in Consul. +- Use [Envoy proxies](/consul/docs/connect/proxies/envoy). Envoy is the only proxy with mesh gateway capabilities in Consul. ## Configuration @@ -47,10 +47,10 @@ Configure the following settings to register and use the mesh gateway as a servi Register a mesh gateway in each of cluster that will be peered. - Specify `mesh-gateway` in the `kind` field to register the gateway with Consul. -- Define the `Proxy.Config` settings using opaque parameters compatible with your proxy. For Envoy, refer to the [Gateway Options](/docs/connect/proxies/envoy#gateway-options) and [Escape-hatch Overrides](/docs/connect/proxies/envoy#escape-hatch-overrides) documentation for additional configuration information. -- Apply a [Mesh config entry](/docs/connect/config-entries/mesh#peer-through-mesh-gateways) with `PeerThroughMeshGateways = true`. See [modes](#modes) for a discussion of when to apply this. +- Define the `Proxy.Config` settings using opaque parameters compatible with your proxy. For Envoy, refer to the [Gateway Options](/consul/docs/connect/proxies/envoy#gateway-options) and [Escape-hatch Overrides](/consul/docs/connect/proxies/envoy#escape-hatch-overrides) documentation for additional configuration information. +- Apply a [Mesh config entry](/consul/docs/connect/config-entries/mesh#peer-through-mesh-gateways) with `PeerThroughMeshGateways = true`. See [modes](#modes) for a discussion of when to apply this. -Alternatively, you can also use the CLI to spin up and register a gateway in Consul. For additional information, refer to the [`consul connect envoy` command](/commands/connect/envoy#mesh-gateways). +Alternatively, you can also use the CLI to spin up and register a gateway in Consul. For additional information, refer to the [`consul connect envoy` command](/consul/commands/connect/envoy#mesh-gateways). For Consul Enterprise clusters, mesh gateways must be registered in the "default" partition because this is implicitly where Consul servers are assigned. @@ -59,7 +59,7 @@ For Consul Enterprise clusters, mesh gateways must be registered in the "default -In addition to the [ACL Configuration](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers#acl-configuration) necessary for service-to-service traffic, mesh gateways that route peering control plane traffic must be granted `peering:read` access to all peerings. +In addition to the [ACL Configuration](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers#acl-configuration) necessary for service-to-service traffic, mesh gateways that route peering control plane traffic must be granted `peering:read` access to all peerings. This access allows the mesh gateway to list all peerings in a Consul cluster and generate unique routing per peered datacenter. @@ -80,7 +80,7 @@ peering = "read" -In addition to the [ACL Configuration](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers#acl-configuration) necessary for service-to-service traffic, mesh gateways that route peering control plane traffic must be granted `peering:read` access to all peerings in all partitions. +In addition to the [ACL Configuration](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers#acl-configuration) necessary for service-to-service traffic, mesh gateways that route peering control plane traffic must be granted `peering:read` access to all peerings in all partitions. This access allows the mesh gateway to list all peerings in a Consul cluster and generate unique routing per peered partition. @@ -108,8 +108,8 @@ partition_prefix "" { ### Modes -Connect proxy configuration [Modes](/docs/connect/gateways/mesh-gateway#connect-proxy-configuration#modes) are not applicable to peering control plane traffic. -The flow of control plane traffic through the gateway is implied by the presence of a [Mesh config entry](/docs/connect/config-entries/mesh#peer-through-mesh-gateways) with `PeerThroughMeshGateways = true`. +Connect proxy configuration [Modes](/consul/docs/connect/gateways/mesh-gateway#connect-proxy-configuration#modes) are not applicable to peering control plane traffic. +The flow of control plane traffic through the gateway is implied by the presence of a [Mesh config entry](/consul/docs/connect/config-entries/mesh#peer-through-mesh-gateways) with `PeerThroughMeshGateways = true`. @@ -127,9 +127,9 @@ Peeering: ``` -By setting this mesh config on a cluster before [creating a peering token](/docs/connect/cluster-peering/create-manage-peering#create-a-peering-token), inbound control plane traffic will be sent through the mesh gateway registered this cluster, also known the accepting cluster. +By setting this mesh config on a cluster before [creating a peering token](/consul/docs/connect/cluster-peering/create-manage-peering#create-a-peering-token), inbound control plane traffic will be sent through the mesh gateway registered this cluster, also known the accepting cluster. As mesh gateway instances are registered at the accepting cluster, their addresses will be exposed to the dialing cluster over the bi-directional peering stream. -Setting this mesh config on a cluster before [establishing a connection](/docs/connect/cluster-peering/create-manage-peering#establish-a-connection-between-clusters) will cause the outbound control plane traffic to flow through the mesh gateway. +Setting this mesh config on a cluster before [establishing a connection](/consul/docs/connect/cluster-peering/create-manage-peering#establish-a-connection-between-clusters) will cause the outbound control plane traffic to flow through the mesh gateway. To route all peering control plane traffic though mesh gateways, both the accepting and dialing cluster must have the mesh config entry applied. diff --git a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions.mdx b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions.mdx index 409705d6b8..d993b70f69 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions.mdx @@ -9,7 +9,7 @@ description: >- -> **Consul Enterprise 1.11.0+:** Admin partitions are supported in Consul Enterprise versions 1.11.0 and newer. -Mesh gateways enable you to route service mesh traffic between different Consul [admin partitions](/docs/enterprise/admin-partitions). +Mesh gateways enable you to route service mesh traffic between different Consul [admin partitions](/consul/docs/enterprise/admin-partitions). Partitions can reside in different clouds or runtime environments where general interconnectivity between all services in all partitions isn't feasible. @@ -23,9 +23,9 @@ Ensure that your Consul environment meets the following requirements. * Consul Enterprise version 1.11.0 or newer. * A local Consul agent is required to manage its configuration. -* Consul service mesh must be enabled in all partitions. Refer to the [`connect` documentation](/docs/agent/config/config-files#connect) for details. -* Each partition must have a unique name. Refer to the [admin partitions documentation](/docs/enterprise/admin-partitions) for details. -* If you want to [enable gateways globally](/docs/connect/gateways/mesh-gateway#enabling-gateways-globally) you must enable [centralized configuration](/docs/agent/config/config-files#enable_central_service_config). +* Consul service mesh must be enabled in all partitions. Refer to the [`connect` documentation](/consul/docs/agent/config/config-files#connect) for details. +* Each partition must have a unique name. Refer to the [admin partitions documentation](/consul/docs/enterprise/admin-partitions) for details. +* If you want to [enable gateways globally](/consul/docs/connect/gateways/mesh-gateway#enabling-gateways-globally) you must enable [centralized configuration](/consul/docs/agent/config/config-files#enable_central_service_config). ### Proxy @@ -43,9 +43,9 @@ Sidecar proxies that do not send upstream traffic through a gateway are not affe Configure the following settings to register the mesh gateway as a service in Consul. * Specify `mesh-gateway` in the `kind` field to register the gateway with Consul. -* Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and partition. Refer to the [`upstreams` documentation](/docs/connect/registration/service-registration#upstream-configuration-reference) for details. The service `proxy.upstreams.destination_name` is always required. The `proxy.upstreams.destination_partition` must be configured to enable cross-partition traffic. The `proxy.upstreams.destination_namespace` configuration is only necessary if the destination service is in a different namespace. -* Configure the `exported-services` configuration entry to enable Consul to export services contained in an admin partition to one or more additional partitions. Refer to the [Exported Services documentation](/docs/connect/config-entries/exported-services) for details. -* Define the `Proxy.Config` settings using opaque parameters compatible with your proxy, i.e., Envoy. For Envoy, refer to the [Gateway Options](/docs/connect/proxies/envoy#gateway-options) and [Escape-hatch Overrides](/docs/connect/proxies/envoy#escape-hatch-overrides) documentation for additional configuration information. +* Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and partition. Refer to the [`upstreams` documentation](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) for details. The service `proxy.upstreams.destination_name` is always required. The `proxy.upstreams.destination_partition` must be configured to enable cross-partition traffic. The `proxy.upstreams.destination_namespace` configuration is only necessary if the destination service is in a different namespace. +* Configure the `exported-services` configuration entry to enable Consul to export services contained in an admin partition to one or more additional partitions. Refer to the [Exported Services documentation](/consul/docs/connect/config-entries/exported-services) for details. +* Define the `Proxy.Config` settings using opaque parameters compatible with your proxy, i.e., Envoy. For Envoy, refer to the [Gateway Options](/consul/docs/connect/proxies/envoy#gateway-options) and [Escape-hatch Overrides](/consul/docs/connect/proxies/envoy#escape-hatch-overrides) documentation for additional configuration information. * If ACLs are enabled, a token granting `service:write` for the gateway's service name and `service:read` for all services in the datacenter or partition must be added to the gateway's service definition. These permissions authorize the token to route communications for other Consul service mesh services, but does not allow decrypting any of their communications. ### Modes @@ -121,7 +121,7 @@ Name: web ### Enabling Gateways for a Service Instance -The following [Proxy Service Registration](/docs/connect/registration/service-registration) +The following [Proxy Service Registration](/consul/docs/connect/registration/service-registration) definition will enable gateways for `web` service instances in the `finance` partition. diff --git a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx index 4adeecaf1a..ee5a3e38d3 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers.mdx @@ -21,7 +21,7 @@ To configure mesh gateways for cluster peering, make sure your Consul environmen - Consul version 1.14.0 or newer. - A local Consul agent is required to manage mesh gateway configuration. -- Use [Envoy proxies](/docs/connect/proxies/envoy). Envoy is the only proxy with mesh gateway capabilities in Consul. +- Use [Envoy proxies](/consul/docs/connect/proxies/envoy). Envoy is the only proxy with mesh gateway capabilities in Consul. ## Configuration @@ -30,20 +30,20 @@ Configure the following settings to register and use the mesh gateway as a servi ### Gateway registration - Specify `mesh-gateway` in the `kind` field to register the gateway with Consul. -- Define the `Proxy.Config` settings using opaque parameters compatible with your proxy. For Envoy, refer to the [Gateway Options](/docs/connect/proxies/envoy#gateway-options) and [Escape-hatch Overrides](/docs/connect/proxies/envoy#escape-hatch-overrides) documentation for additional configuration information. +- Define the `Proxy.Config` settings using opaque parameters compatible with your proxy. For Envoy, refer to the [Gateway Options](/consul/docs/connect/proxies/envoy#gateway-options) and [Escape-hatch Overrides](/consul/docs/connect/proxies/envoy#escape-hatch-overrides) documentation for additional configuration information. -Alternatively, you can also use the CLI to spin up and register a gateway in Consul. For additional information, refer to the [`consul connect envoy` command](/commands/connect/envoy#mesh-gateways). +Alternatively, you can also use the CLI to spin up and register a gateway in Consul. For additional information, refer to the [`consul connect envoy` command](/consul/commands/connect/envoy#mesh-gateways). ### Sidecar registration -- Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and peer. Refer to the [`upstreams` documentation](/docs/connect/registration/service-registration#upstream-configuration-reference) for details. +- Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and peer. Refer to the [`upstreams` documentation](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) for details. - The service `proxy.upstreams.destination_name` is always required. - The `proxy.upstreams.destination_peer` must be configured to enable cross-cluster traffic. - The `proxy.upstream/destination_namespace` configuration is only necessary if the destination service is in a non-default namespace. ### Service exports -- Include the `exported-services` configuration entry to enable Consul to export services contained in a cluster to one or more additional clusters. For additional information, refer to the [Exported Services documentation](/docs/connect/config-entries/exported-services). +- Include the `exported-services` configuration entry to enable Consul to export services contained in a cluster to one or more additional clusters. For additional information, refer to the [Exported Services documentation](/consul/docs/connect/config-entries/exported-services). ### ACL configuration @@ -57,4 +57,4 @@ This permission allows a leaf certificate to be issued for mesh gateways to term Modes are configurable as either `remote` or `local` for mesh gateways that connect peered clusters. The `none` setting is invalid for mesh gateways in peered clusters and will be ignored by the gateway. -By default, all proxies connecting to peered clusters use mesh gateways in [remote mode](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters#remote). +By default, all proxies connecting to peered clusters use mesh gateways in [remote mode](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters#remote). diff --git a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters.mdx b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters.mdx index 32370c8e34..690dc99945 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters.mdx @@ -19,7 +19,7 @@ The following diagram describes the architecture for using mesh gateways for cro ![Mesh Gateway Architecture](/img/mesh-gateways.png) --> **Mesh Gateway Tutorial**: Follow the [mesh gateway tutorial](https://learn.hashicorp.com/tutorials/consul/service-mesh-gateways) to learn important concepts associated with using mesh gateways for connecting services across datacenters. +-> **Mesh Gateway Tutorial**: Follow the [mesh gateway tutorial](/consul/tutorials/developer-mesh/service-mesh-gateways) to learn important concepts associated with using mesh gateways for connecting services across datacenters. ## Prerequisites @@ -29,12 +29,12 @@ Ensure that your Consul environment meets the following requirements. * Consul version 1.6.0 or newer. * A local Consul agent is required to manage its configuration. -* Consul [Connect](/docs/agent/config/config-files#connect) must be enabled in both datacenters. -* Each [datacenter](/docs/agent/config/config-files#datacenter) must have a unique name. +* Consul [Connect](/consul/docs/agent/config/config-files#connect) must be enabled in both datacenters. +* Each [datacenter](/consul/docs/agent/config/config-files#datacenter) must have a unique name. * Each datacenters must be [WAN joined](https://learn.hashicorp.com/consul/security-networking/datacenters). -* The [primary datacenter](/docs/agent/config/config-files#primary_datacenter) must be set to the same value in both datacenters. This specifies which datacenter is the authority for Connect certificates and is required for services in all datacenters to establish mutual TLS with each other. -* [gRPC](/docs/agent/config/config-files#grpc_port) must be enabled. -* If you want to [enable gateways globally](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters#enabling-gateways-globally) you must enable [centralized configuration](/docs/agent/config/config-files#enable_central_service_config). +* The [primary datacenter](/consul/docs/agent/config/config-files#primary_datacenter) must be set to the same value in both datacenters. This specifies which datacenter is the authority for Connect certificates and is required for services in all datacenters to establish mutual TLS with each other. +* [gRPC](/consul/docs/agent/config/config-files#grpc_port) must be enabled. +* If you want to [enable gateways globally](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters#enabling-gateways-globally) you must enable [centralized configuration](/consul/docs/agent/config/config-files#enable_central_service_config). ### Network @@ -57,8 +57,8 @@ Sidecar proxies that do not send upstream traffic through a gateway are not affe Configure the following settings to register the mesh gateway as a service in Consul. * Specify `mesh-gateway` in the `kind` field to register the gateway with Consul. -* Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and datacenter. Refer to the [`upstreams` documentation](/docs/connect/registration/service-registration#upstream-configuration-reference) for details. The service `proxy.upstreams.destination_name` is always required. The `proxy.upstreams.datacenter` must be configured to enable cross-datacenter traffic. The `proxy.upstreams.destination_namespace` configuration is only necessary if the destination service is in a different namespace. -* Define the `Proxy.Config` settings using opaque parameters compatible with your proxy (i.e., Envoy). For Envoy, refer to the [Gateway Options](/docs/connect/proxies/envoy#gateway-options) and [Escape-hatch Overrides](/docs/connect/proxies/envoy#escape-hatch-overrides) documentation for additional configuration information. +* Configure the `proxy.upstreams` parameters to route traffic to the correct service, namespace, and datacenter. Refer to the [`upstreams` documentation](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) for details. The service `proxy.upstreams.destination_name` is always required. The `proxy.upstreams.datacenter` must be configured to enable cross-datacenter traffic. The `proxy.upstreams.destination_namespace` configuration is only necessary if the destination service is in a different namespace. +* Define the `Proxy.Config` settings using opaque parameters compatible with your proxy (i.e., Envoy). For Envoy, refer to the [Gateway Options](/consul/docs/connect/proxies/envoy#gateway-options) and [Escape-hatch Overrides](/consul/docs/connect/proxies/envoy#escape-hatch-overrides) documentation for additional configuration information. * If ACLs are enabled, a token granting `service:write` for the gateway's service name and `service:read` for all services in the datacenter or partition must be added to the gateway's service definition. These permissions authorize the token to route communications for other Consul service mesh services, but does not allow decrypting any of their communications. ### Modes @@ -137,7 +137,7 @@ Name: web ### Enabling Gateways for a Service Instance -The following [Proxy Service Registration](/docs/connect/registration/service-registration) +The following [Proxy Service Registration](/consul/docs/connect/registration/service-registration) definition will enable gateways for the service instance in the `remote` mode. diff --git a/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx b/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx index a1a25414f0..643734ec95 100644 --- a/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx +++ b/website/content/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways.mdx @@ -9,7 +9,7 @@ description: >- -> **1.8.0+:** This feature is available in Consul versions 1.8.0 and higher -~> This topic requires familiarity with [mesh gateways](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters). +~> This topic requires familiarity with [mesh gateways](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters). WAN federation via mesh gateways allows for Consul servers in different datacenters to be federated exclusively through mesh gateways. @@ -38,7 +38,7 @@ Sometimes this prerequisite is difficult or undesirable to meet: Operators looking to simplify their WAN deployment and minimize the exposed security surface area can elect to join these datacenters together using [mesh -gateways](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters) to do so. +gateways](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters) to do so. [![WAN federation with mesh gateways](/img/wan-federation-connectivity-mesh-gateways.png)](/img/wan-federation-connectivity-mesh-gateways.png) @@ -63,7 +63,7 @@ means you could introduce a set of firewall rules prohibiting `10.0.0.0/24` from sending any traffic at all to `10.1.2.0/24` for security isolation. You may already have configured [mesh -gateways](https://learn.hashicorp.com/tutorials/consul/service-mesh-gateways) +gateways](/consul/tutorials/developer-mesh/service-mesh-gateways) to allow for services in the service mesh to freely connect between datacenters regardless of the lateral connectivity of the nodes hosting the Consul client agents. @@ -126,8 +126,8 @@ connect { } ``` -The [`retry_join_wan`](/docs/agent/config/config-files#retry_join_wan) addresses are -only used for the [traditional federation process](/docs/k8s/deployment-configurations/multi-cluster#traditional-wan-federation). +The [`retry_join_wan`](/consul/docs/agent/config/config-files#retry_join_wan) addresses are +only used for the [traditional federation process](/consul/docs/k8s/deployment-configurations/multi-cluster#traditional-wan-federation). They must be omitted when federating Consul servers via gateways. -> The `primary_gateways` configuration can also use `go-discover` syntax just @@ -181,7 +181,7 @@ expected result: their _local_ ip addresses and are listed as `alive`. - Ensure any API request that activates datacenter request forwarding. such as - [`/v1/catalog/services?dc=`](/api-docs/catalog#dc-1) + [`/v1/catalog/services?dc=`](/consul/api-docs/catalog#dc-1) succeeds. ### Upgrading the primary gateways @@ -194,7 +194,7 @@ If the primary gateways are upgraded, and their previous instances are decommiss before the updates are propagated, then the primary datacenter will become unreachable. To safely upgrade primary gateways, we recommend that you apply one of the following policies: -- Avoid decommissioning primary gateway IP addresses. This is because the [primary_gateways](/docs/agent/config/config-files#primary_gateways) addresses configured on the secondary servers act as a fallback mechanism for re-establishing connectivity to the primary. +- Avoid decommissioning primary gateway IP addresses. This is because the [primary_gateways](/consul/docs/agent/config/config-files#primary_gateways) addresses configured on the secondary servers act as a fallback mechanism for re-establishing connectivity to the primary. - Verify that addresses of the new mesh gateways in the primary were propagated to the secondary datacenters before decommissioning the old mesh gateways in the primary. diff --git a/website/content/docs/connect/gateways/terminating-gateway.mdx b/website/content/docs/connect/gateways/terminating-gateway.mdx index 5628d86a75..05f48eee5f 100644 --- a/website/content/docs/connect/gateways/terminating-gateway.mdx +++ b/website/content/docs/connect/gateways/terminating-gateway.mdx @@ -10,30 +10,30 @@ description: >- -> **1.8.0+:** This feature is available in Consul versions 1.8.0 and newer. Terminating gateways enable connectivity within your organizational network from services in the Consul service mesh to -services and [destinations](/docs/connect/config-entries/service-defaults#terminating-gateway-destination) outside the mesh. These gateways effectively act as Connect proxies that can +services and [destinations](/consul/docs/connect/config-entries/service-defaults#terminating-gateway-destination) outside the mesh. These gateways effectively act as Connect proxies that can represent more than one service. They terminate Connect mTLS connections, enforce intentions, and forward requests to the appropriate destination. ![Terminating Gateway Architecture](/img/terminating-gateways.png) For additional use cases and usage patterns, review the tutorial for -[understanding terminating gateways](https://learn.hashicorp.com/tutorials/consul/service-mesh-terminating-gateways?utm_source=docs). +[understanding terminating gateways](/consul/tutorials/developer-mesh/service-mesh-terminating-gateways?utm_source=docs). ~> **Known limitations:** Terminating gateways currently do not support targeting service subsets with -[L7 configuration](/docs/connect/l7-traffic). They route to all instances of a service with no capabilities +[L7 configuration](/consul/docs/connect/l7-traffic). They route to all instances of a service with no capabilities for filtering by instance. ## Security Considerations ~> We recommend that terminating gateways are not exposed to the WAN or open internet. This is because terminating gateways hold certificates to decrypt Consul Connect traffic directed at them and may be configured with credentials to connect -to linked services. Connections over the WAN or open internet should flow through [mesh gateways](/docs/connect/gateways/mesh-gateway) +to linked services. Connections over the WAN or open internet should flow through [mesh gateways](/consul/docs/connect/gateways/mesh-gateway) whenever possible since they are not capable of decrypting traffic or connecting directly to services. -By specifying a path to a [CA file](/docs/connect/config-entries/terminating-gateway#cafile) connections +By specifying a path to a [CA file](/consul/docs/connect/config-entries/terminating-gateway#cafile) connections from the terminating gateway will be encrypted using one-way TLS authentication. If a path to a -[client certificate](/docs/connect/config-entries/terminating-gateway#certfile) -and [private key](/docs/connect/config-entries/terminating-gateway#keyfile) are also specified connections +[client certificate](/consul/docs/connect/config-entries/terminating-gateway#certfile) +and [private key](/consul/docs/connect/config-entries/terminating-gateway#keyfile) are also specified connections from the terminating gateway will be encrypted using mutual TLS authentication. If none of these are provided, Consul will **only** encrypt connections to the gateway and not @@ -41,7 +41,7 @@ from the gateway to the destination service. When certificates for linked services are rotated, the gateway must be restarted to pick up the new certificates from disk. To avoid downtime, perform a rolling restart to reload the certificates. Registering multiple terminating gateway instances -with the same [name](/commands/connect/envoy#service) provides additional fault tolerance +with the same [name](/consul/commands/connect/envoy#service) provides additional fault tolerance as well as the ability to perform rolling restarts. -> **Note:** If certificates and keys are configured the terminating gateway will upgrade HTTP connections to TLS. @@ -58,8 +58,8 @@ Each terminating gateway needs: Terminating gateways also require that your Consul datacenters are configured correctly: - You'll need to use Consul version 1.8.0 or newer. -- Consul [Connect](/docs/agent/config/config-files#connect) must be enabled on the datacenter's Consul servers. -- [gRPC](/docs/agent/config/config-files#grpc_port) must be enabled on all client agents. +- Consul [Connect](/consul/docs/agent/config/config-files#connect) must be enabled on the datacenter's Consul servers. +- [gRPC](/consul/docs/agent/config/config-files#grpc_port) must be enabled on all client agents. Currently, [Envoy](https://www.envoyproxy.io/) is the only proxy with terminating gateway capabilities in Consul. @@ -72,21 +72,21 @@ Connect proxies that send upstream traffic through a gateway aren't affected when you deploy terminating gateways. If you are using non-Envoy proxies as Connect proxies they will continue to work for traffic directed at services linked to a terminating gateway as long as they discover upstreams with the -[/health/connect](/api-docs/health#list-nodes-for-connect-capable-service) endpoint. +[/health/connect](/consul/api-docs/health#list-nodes-for-connect-capable-service) endpoint. ## Running and Using a Terminating Gateway For a complete example of how to enable connections from services in the Consul service mesh to -services outside the mesh, review the [terminating gateway tutorial](https://learn.hashicorp.com/tutorials/consul/terminating-gateways-connect-external-services). +services outside the mesh, review the [terminating gateway tutorial](/consul/tutorials/developer-mesh/terminating-gateways-connect-external-services). ## Terminating Gateway Configuration Terminating gateways are configured in service definitions and registered with Consul like other services, with two exceptions. -The first is that the [kind](/api-docs/agent/service#kind) must be "terminating-gateway". Second, +The first is that the [kind](/consul/api-docs/agent/service#kind) must be "terminating-gateway". Second, the terminating gateway service definition may contain a `Proxy.Config` entry just like a Connect proxy service, to define opaque configuration parameters useful for the actual proxy software. -For Envoy there are some supported [gateway options](/docs/connect/proxies/envoy#gateway-options) as well as -[escape-hatch overrides](/docs/connect/proxies/envoy#escape-hatch-overrides). +For Envoy there are some supported [gateway options](/consul/docs/connect/proxies/envoy#gateway-options) as well as +[escape-hatch overrides](/consul/docs/connect/proxies/envoy#escape-hatch-overrides). -> **Note:** If ACLs are enabled, terminating gateways must be registered with a token granting `node:read` on the nodes of all services in its configuration entry. The token must also grant `service:write` for the terminating gateway's service name **and** @@ -96,35 +96,35 @@ If the Consul client agent on the gateway's node is not configured to use the de must also provide `agent:read` for its node's name in order to discover the agent's gRPC port. gRPC is used to expose Envoy's xDS API to Envoy proxies. You can link services and destinations to a terminating gateway with a `terminating-gateway` -[configuration entry](/docs/connect/config-entries/terminating-gateway). This config entry can be applied via the -[CLI](/commands/config/write) or [API](/api-docs/config#apply-configuration). +[configuration entry](/consul/docs/connect/config-entries/terminating-gateway). This config entry can be applied via the +[CLI](/consul/commands/config/write) or [API](/consul/api-docs/config#apply-configuration). Gateways with the same name in Consul's service catalog are configured with a single configuration entry. This means that additional gateway instances registered with the same name will determine their routing based on the existing configuration entry. Adding replicas of a gateway that routes to a particular set of services requires running the -[envoy subcommand](/commands/connect/envoy#terminating-gateways) on additional hosts and specifying +[envoy subcommand](/consul/commands/connect/envoy#terminating-gateways) on additional hosts and specifying the same gateway name with the `service` flag. -~> [Configuration entries](/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies +~> [Configuration entries](/consul/docs/agent/config-entries) are global in scope. A configuration entry for a gateway name applies across all federated Consul datacenters. If terminating gateways in different Consul datacenters need to route to different sets of services within their datacenter then the terminating gateways **must** be registered with different names. The services that the terminating gateway will proxy for must be registered with Consul, even the services outside the mesh. They must also be registered in the same Consul datacenter as the terminating gateway. Otherwise the terminating gateway will not be able to discover the services' addresses. These services can be registered with a local Consul agent. -If there is no agent present, the services can be registered [directly in the catalog](/api-docs/catalog#register-entity) +If there is no agent present, the services can be registered [directly in the catalog](/consul/api-docs/catalog#register-entity) by sending the registration request to a client or server agent on a different host. All services registered in the Consul catalog must be associated with a node, even when their node is not managed by a Consul client agent. All agent-less services with the same address can be registered under the same node name and address. -However, ensure that the [node name](/api-docs/catalog#node) for external services registered directly in the catalog +However, ensure that the [node name](/consul/api-docs/catalog#node) for external services registered directly in the catalog does not match the node name of any Consul client agent node. If the node name overlaps with the node name of a Consul client agent, -Consul's [anti-entropy sync](/docs/architecture/anti-entropy) will delete the services registered via the `/catalog/register` HTTP API endpoint. +Consul's [anti-entropy sync](/consul/docs/architecture/anti-entropy) will delete the services registered via the `/catalog/register` HTTP API endpoint. -Service-defaults [destinations](/docs/connect/config-entries/service-defaults#destination) let you +Service-defaults [destinations](/consul/docs/connect/config-entries/service-defaults#destination) let you define endpoints external to the mesh and routable through a terminating gateway in transparent mode. After you define a service-defaults configuration entry for each destination, you can use the service-default name as part of the terminating gateway services list. If a service and a destination service-defaults have the same name, the terminating gateway will use the service. For a complete example of how to register external services review the -[external services tutorial](https://learn.hashicorp.com/tutorials/consul/service-registration-external-services). +[external services tutorial](/consul/tutorials/developer-discovery/service-registration-external-services). diff --git a/website/content/docs/connect/index.mdx b/website/content/docs/connect/index.mdx index a609674bd8..cbd2903a33 100644 --- a/website/content/docs/connect/index.mdx +++ b/website/content/docs/connect/index.mdx @@ -10,9 +10,9 @@ description: >- Consul Service Mesh provides service-to-service connection authorization and encryption using mutual Transport Layer Security (TLS). Consul Connect is used interchangeably with the name Consul Service Mesh and is what this document will use to refer to for Service Mesh functionality within Consul. -Applications can use [sidecar proxies](/docs/connect/proxies) in a service mesh configuration to +Applications can use [sidecar proxies](/consul/docs/connect/proxies) in a service mesh configuration to establish TLS connections for inbound and outbound connections without being aware of Connect at all. -Applications may also [natively integrate with Connect](/docs/connect/native) for optimal performance and security. +Applications may also [natively integrate with Connect](/consul/docs/connect/native) for optimal performance and security. Connect can help you secure your services and provide data about service-to-service communications. Review the video below to learn more about Consul Connect from HashiCorp's co-founder Armon. @@ -30,7 +30,7 @@ Review the video below to learn more about Consul Connect from HashiCorp's co-fo Connect enables secure deployment best-practices with automatic service-to-service encryption, and identity-based authorization. Connect uses the registered service identity (rather than IP addresses) to -enforce access control with [intentions](/docs/connect/intentions). This +enforce access control with [intentions](/consul/docs/connect/intentions). This makes it easier to reason about access control and enables services to be rescheduled by orchestrators including Kubernetes and Nomad. Intention enforcement is network agnostic, so Connect works with physical networks, cloud @@ -50,24 +50,24 @@ applications can also send open tracing data through Envoy. There are several ways to try Connect in different environments. -- The [Getting Started with Consul Service Mesh collection](https://learn.hashicorp.com/tutorials/consul/service-mesh?utm_source=docs) +- The [Getting Started with Consul Service Mesh collection](/consul/tutorials/kubernetes-deploy/service-mesh?utm_source=docs) walks you through installing Consul as service mesh for Kubernetes using the Helm chart, deploying services in the service mesh, and using intentions to secure service communications. -- The [Getting Started With Consul for Kubernetes](https://developer.hashicorp.com/consul/tutorials/get-started-kubernetes?utm_source=docs) tutorials guides you through installing Consul on Kubernetes to set up a service mesh for establishing communication between Kubernetes services. +- The [Getting Started With Consul for Kubernetes](/consul/tutorials/get-started-kubernetes?utm_source=docs) tutorials guides you through installing Consul on Kubernetes to set up a service mesh for establishing communication between Kubernetes services. -- The [Secure Service-to-Service Communication tutorial](https://learn.hashicorp.com/tutorials/consul/service-mesh-with-envoy-proxy?utm_source=docs) +- The [Secure Service-to-Service Communication tutorial](/consul/tutorials/developer-mesh/service-mesh-with-envoy-proxy?utm_source=docs) is a simple walk through of connecting two services on your local machine using Consul Connect's built-in proxy and configuring your first intention. The guide also includes an introduction to using Envoy as the Connect sidecar proxy. -- The [Kubernetes tutorial](https://learn.hashicorp.com/tutorials/consul/kubernetes-minikube?utm_source=docs) +- The [Kubernetes tutorial](/consul/tutorials/kubernetes/kubernetes-minikube?utm_source=docs) walks you through configuring Consul Connect in Kubernetes using the Helm chart, and using intentions. You can run the guide on Minikube or an existing Kubernetes cluster. -- The [observability tutorial](https://learn.hashicorp.com/tutorials/consul/kubernetes-layer7-observability?in=consul/kubernetes) +- The [observability tutorial](/consul/tutorials/kubernetes/kubernetes-layer7-observability) shows how to deploy a basic metrics collection and visualization pipeline on a Minikube or Kubernetes cluster using the official Helm charts for Consul, Prometheus, and Grafana. diff --git a/website/content/docs/connect/intentions-legacy.mdx b/website/content/docs/connect/intentions-legacy.mdx index 901f1880b6..0e9e991d37 100644 --- a/website/content/docs/connect/intentions-legacy.mdx +++ b/website/content/docs/connect/intentions-legacy.mdx @@ -9,33 +9,33 @@ description: >- ~> **1.8.x and earlier:** This document only applies in Consul versions 1.8.x and before. If you are using version 1.9.0 or later please use the updated -documentation [here](/docs/connect/intentions). +documentation [here](/consul/docs/connect/intentions). Intentions define access control for services via Connect and are used to control which services may establish connections. Intentions can be managed via the API, CLI, or UI. -Intentions are enforced by the [proxy](/docs/connect/proxies) -or [natively integrated application](/docs/connect/native) on +Intentions are enforced by the [proxy](/consul/docs/connect/proxies) +or [natively integrated application](/consul/docs/connect/native) on inbound connections. After verifying the TLS client certificate, the -[authorize API endpoint](/api-docs/agent/connect#authorize) is called which verifies the connection +[authorize API endpoint](/consul/api-docs/agent/connect#authorize) is called which verifies the connection is allowed by testing the intentions. If authorize returns false the connection must be terminated. The default intention behavior is defined by the default [ACL -policy](/docs/agent/config/config-files#acl_default_policy). If the default ACL policy is +policy](/consul/docs/agent/config/config-files#acl_default_policy). If the default ACL policy is "allow all", then all Connect connections are allowed by default. If the default ACL policy is "deny all", then all Connect connections are denied by default. ## Intention Basics -Intentions can be managed via the [API](/api-docs/connect/intentions), -[CLI](/commands/intention), or UI. Please see the respective documentation for +Intentions can be managed via the [API](/consul/api-docs/connect/intentions), +[CLI](/consul/commands/intention), or UI. Please see the respective documentation for each for full details on options, flags, etc. Below is an example of a basic intention to show the basic attributes of an intention. The full data model of an intention can be found in the [API -documentation](/api-docs/connect/intentions). +documentation](/consul/api-docs/connect/intentions). ```shell-session $ consul intention create -deny web db @@ -105,7 +105,7 @@ top to bottom, with larger numbers being evaluated first. | Exact | `*` | `*` | `*` | 2 | | `*` | `*` | `*` | `*` | 1 | -The precedence value can be read from the [API](/api-docs/connect/intentions) +The precedence value can be read from the [API](/consul/api-docs/connect/intentions) after an intention is created. Precedence cannot be manually overridden today. This is a feature that will be added in a later version of Consul. @@ -124,7 +124,7 @@ the table with a `*` for either the source namespace or destination namespace ar ## Intention Management Permissions -Intention management can be protected by [ACLs](/docs/security/acl). +Intention management can be protected by [ACLs](/consul/docs/security/acl). Permissions for intentions are _destination-oriented_, meaning the ACLs for managing intentions are looked up based on the destination value of the intention, not the source. diff --git a/website/content/docs/connect/intentions.mdx b/website/content/docs/connect/intentions.mdx index d2bdff0fb0..b3b0371a93 100644 --- a/website/content/docs/connect/intentions.mdx +++ b/website/content/docs/connect/intentions.mdx @@ -9,15 +9,15 @@ description: >- -> **1.9.0 and later:** This guide only applies in Consul versions 1.9.0 and later. The documentation for the legacy intentions system is -[here](/docs/connect/intentions-legacy). +[here](/consul/docs/connect/intentions-legacy). Intentions define access control for services via Connect and are used to control which services may establish connections or make requests. Intentions can be managed via the API, CLI, or UI. Intentions are enforced on inbound connections or requests by the -[proxy](/docs/connect/proxies) or within a [natively integrated -application](/docs/connect/native). +[proxy](/consul/docs/connect/proxies) or within a [natively integrated +application](/consul/docs/connect/native). Depending upon the [protocol] in use by the destination service, you can define intentions to control Connect traffic authorization either at networking layer @@ -25,7 +25,7 @@ intentions to control Connect traffic authorization either at networking layer - **Identity-based** - All intentions may enforce access based on identities encoded within [TLS - certificates](/docs/connect/connect-internals#mutual-transport-layer-security-mtls). + certificates](/consul/docs/connect/connect-internals#mutual-transport-layer-security-mtls). This allows for coarse all-or-nothing access control between pairs of services. These work with for services with any [protocol] as they only require awareness of the TLS handshake that wraps the opaque TCP connection. @@ -33,7 +33,7 @@ intentions to control Connect traffic authorization either at networking layer - **Application-aware** - Some intentions may additionally enforce access based on [L7 request - attributes](/docs/connect/config-entries/service-intentions#permissions) in + attributes](/consul/docs/connect/config-entries/service-intentions#permissions) in addition to connection identity. These may only be defined for services with a [protocol] that is HTTP-based. These can also be thought of as **L7 intentions**. @@ -42,21 +42,21 @@ At any given point in time, between any pair of services **only one intention controls authorization**. This may be either an L4 intention or an L7 intention, but at any given point in time only one of those applies. -The [intention match API](/api-docs/connect/intentions#list-matching-intentions) +The [intention match API](/consul/api-docs/connect/intentions#list-matching-intentions) should be periodically called to retrieve all relevant intentions for the target destination. After verifying the TLS client certificate, the cached intentions should be consulted for each incoming connection/request to determine if it should be accepted or rejected. -The default intention behavior is defined by the [`default_policy`](/docs/agent/config/config-files#acl_default_policy) configuration. +The default intention behavior is defined by the [`default_policy`](/consul/docs/agent/config/config-files#acl_default_policy) configuration. If the configuration is set `allow`, then all service mesh Connect connections will be allowed by default. If is set to `deny`, then all connections or requests will be denied by default. ## Intention Basics -You can define a [`service-intentions`](/docs/connect/config-entries/service-intentions) configuration entry to create and manage intentions, as well as manage intentions through the Consul UI. You can also perform some intention-related tasks using the API and CLI commands. Refer to the [API](/api-docs/connect/intentions) and [CLI](/commands/intention) documentation for details. +You can define a [`service-intentions`](/consul/docs/connect/config-entries/service-intentions) configuration entry to create and manage intentions, as well as manage intentions through the Consul UI. You can also perform some intention-related tasks using the API and CLI commands. Refer to the [API](/consul/api-docs/connect/intentions) and [CLI](/consul/commands/intention) documentation for details. -The following example shows a `service-intentions` configuration entry that specifies two intentions. Refer to the [`service-intentions`](/docs/connect/config-entries/service-intentions) documentation for the full data model and additional examples. +The following example shows a `service-intentions` configuration entry that specifies two intentions. Refer to the [`service-intentions`](/consul/docs/connect/config-entries/service-intentions) documentation for the full data model and additional examples. @@ -105,7 +105,7 @@ accepted. You can use the `*` wildcard to match service names when defining an intention source or destination. The wildcard matches _any_ value, which enables you to set a wide initial scope when configuring intentions. -The wildcard is supported in Consul Enterprise `namespace` fields (see [Namespaces](/docs/enterprise/namespaces) for additional information), but it _is not supported_ in `partition` fields (see [Admin Partitions](/docs/enterprise/admin-partitions) for additional information). +The wildcard is supported in Consul Enterprise `namespace` fields (see [Namespaces](/consul/docs/enterprise/namespaces) for additional information), but it _is not supported_ in `partition` fields (see [Admin Partitions](/consul/docs/enterprise/admin-partitions) for additional information). In the following example, the `web` service cannot connect to _any_ service: @@ -238,7 +238,7 @@ top to bottom, with larger numbers being evaluated first. | `*` | `*` | `*` | `*` | 1 | The precedence value can be read from a -[field](/docs/connect/config-entries/service-intentions#precedence) on the +[field](/consul/docs/connect/config-entries/service-intentions#precedence) on the `service-intentions` configuration entry after it is modified. Precedence cannot be manually overridden today. @@ -251,7 +251,7 @@ rows in this table are not applicable. ## Intention Management Permissions -Intention management can be protected by [ACLs](/docs/security/acl). +Intention management can be protected by [ACLs](/consul/docs/security/acl). Permissions for intentions are _destination-oriented_, meaning the ACLs for managing intentions are looked up based on the destination value of the intention, not the source. @@ -336,6 +336,6 @@ connection authorization continues to work indefinitely. Changes to intentions will not be picked up until the partition heals, but will then automatically take effect when connectivity is restored. -[protocol]: /docs/connect/config-entries/service-defaults#protocol -[proxies]: /docs/connect/proxies -[envoy]: /docs/connect/proxies/envoy +[protocol]: /consul/docs/connect/config-entries/service-defaults#protocol +[proxies]: /consul/docs/connect/proxies +[envoy]: /consul/docs/connect/proxies/envoy diff --git a/website/content/docs/connect/l7-traffic/discovery-chain.mdx b/website/content/docs/connect/l7-traffic/discovery-chain.mdx index e96070e7d1..a41353125e 100644 --- a/website/content/docs/connect/l7-traffic/discovery-chain.mdx +++ b/website/content/docs/connect/l7-traffic/discovery-chain.mdx @@ -9,19 +9,19 @@ description: >- -> **1.6.0+:** This feature is available in Consul versions 1.6.0 and newer. -~> This topic is part of a [low-level API](/api-docs/discovery-chain) +~> This topic is part of a [low-level API](/consul/api-docs/discovery-chain) primarily targeted at developers building external [Connect proxy -integrations](/docs/connect/proxies/integrate). +integrations](/consul/docs/connect/proxies/integrate). The service discovery process can be modeled as a "discovery chain" which passes through three distinct stages: routing, splitting, and resolution. Each of these stages is controlled by a set of [configuration -entries](/docs/agent/config-entries). By configuring different phases of +entries](/consul/docs/agent/config-entries). By configuring different phases of the discovery chain a user can control how proxy upstreams are ultimately resolved to specific instances for load balancing. -> **Note:** The discovery chain is currently only used to discover -[Connect](/docs/connect) proxy upstreams. +[Connect](/consul/docs/connect) proxy upstreams. ## Configuration @@ -29,39 +29,39 @@ The configuration entries used in the discovery chain are designed to be simple to read and modify for narrowly tailored changes, but at discovery-time the various configuration entries interact in more complex ways. For example: -- If a [`service-resolver`](/docs/connect/config-entries/service-resolver) +- If a [`service-resolver`](/consul/docs/connect/config-entries/service-resolver) is created with a [service - redirect](/docs/connect/config-entries/service-resolver#service) defined, + redirect](/consul/docs/connect/config-entries/service-resolver#service) defined, then all references made to the original service in any other configuration entry is replaced with the redirect destination. -- If a [`service-resolver`](/docs/connect/config-entries/service-resolver) +- If a [`service-resolver`](/consul/docs/connect/config-entries/service-resolver) is created with a [default - subset](/docs/connect/config-entries/service-resolver#defaultsubset) + subset](/consul/docs/connect/config-entries/service-resolver#defaultsubset) defined then all references made to the original service in any other configuration entry that did not specify a subset will be replaced with the default. -- If a [`service-splitter`](/docs/connect/config-entries/service-splitter) +- If a [`service-splitter`](/consul/docs/connect/config-entries/service-splitter) is created with a [service - split](/docs/connect/config-entries/service-splitter#splits), and the target service has its + split](/consul/docs/connect/config-entries/service-splitter#splits), and the target service has its own `service-splitter` then the overall effect is flattened and only a single aggregate traffic split is ultimately configured in the proxy. -- [`service-resolver`](/docs/connect/config-entries/service-resolver) +- [`service-resolver`](/consul/docs/connect/config-entries/service-resolver) redirect loops must be rejected as invalid. -- [`service-router`](/docs/connect/config-entries/service-router) and - [`service-splitter`](/docs/connect/config-entries/service-splitter) +- [`service-router`](/consul/docs/connect/config-entries/service-router) and + [`service-splitter`](/consul/docs/connect/config-entries/service-splitter) configuration entries require an L7 compatible protocol be set for the service via either a - [`service-defaults`](/docs/connect/config-entries/service-defaults) or - [`proxy-defaults`](/docs/connect/config-entries/proxy-defaults) config + [`service-defaults`](/consul/docs/connect/config-entries/service-defaults) or + [`proxy-defaults`](/consul/docs/connect/config-entries/proxy-defaults) config entry. Violations must be rejected as invalid. - If an [upstream - configuration](/docs/connect/registration/service-registration#upstream-configuration-reference) - [`datacenter`](/docs/connect/registration/service-registration#datacenter) + configuration](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) + [`datacenter`](/consul/docs/connect/registration/service-registration#datacenter) parameter is defined then any configuration entry that does not explicitly refer to a desired datacenter should use that value from the upstream. @@ -72,7 +72,7 @@ discovery chain, we first compile them into a form more directly usable by the layers responsible for configuring Connect sidecar proxies. You can interact with the compiler directly using the [discovery-chain -API](/api-docs/discovery-chain). +API](/consul/api-docs/discovery-chain). ### Compilation Parameters @@ -80,9 +80,9 @@ API](/api-docs/discovery-chain). - **Datacenter** - The datacenter to use as the basis of compilation. - **Overrides** - Discovery-time tweaks to apply when compiling. These should be derived from either the - [proxy](/docs/connect/registration/service-registration#complete-configuration-example) + [proxy](/consul/docs/connect/registration/service-registration#complete-configuration-example) or - [upstream](/docs/connect/registration/service-registration#upstream-configuration-reference) + [upstream](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) configurations if either are set. ### Compilation Results @@ -100,7 +100,7 @@ The response is a single wrapped `CompiledDiscoveryChain` field: The chain encodes a digraph of [nodes](#discoverygraphnode) and [targets](#discoverytarget). Nodes are the compiled representation of various discovery chain stages and targets are instructions on how to use the [health -API](/api-docs/health#list-nodes-for-connect-capable-service) to retrieve +API](/consul/api-docs/health#list-nodes-for-connect-capable-service) to retrieve relevant service instance lists. You should traverse the nodes starting with [`StartNode`](#startnode). The @@ -157,7 +157,7 @@ A single node in the compiled discovery chain. - `Definition` `(ServiceRoute)` - Relevant portion of underlying `service-router` - [route](/docs/connect/config-entries/service-router#routes). + [route](/consul/docs/connect/config-entries/service-router#routes). - `NextNode` `(string)` - The name of the next node in the chain in [`Nodes`](#nodes). @@ -165,7 +165,7 @@ A single node in the compiled discovery chain. splits. - `Weight` `(float32)` - Copy of underlying `service-splitter` - [`weight`](/docs/connect/config-entries/service-splitter#weight) field. + [`weight`](/consul/docs/connect/config-entries/service-splitter#weight) field. - `NextNode` `(string)` - The name of the next node in the chain in [`Nodes`](#nodes). @@ -176,21 +176,21 @@ A single node in the compiled discovery chain. defined for this node and the default was synthesized. - `ConnectTimeout` `(duration)` - Copy of the underlying `service-resolver` - [`ConnectTimeout`](/docs/connect/config-entries/service-resolver#connecttimeout) + [`ConnectTimeout`](/consul/docs/connect/config-entries/service-resolver#connecttimeout) field. If one is not defined the default of `5s` is returned. - `Target` `(string)` - The name of the target to use found in [`Targets`](#targets). - `Failover` `(DiscoveryFailover: )` - Compiled form of the underlying `service-resolver` - [`Failover`](/docs/connect/config-entries/service-resolver#failover) + [`Failover`](/consul/docs/connect/config-entries/service-resolver#failover) definition to use for this request. - `Targets` `(array)` - List of targets found in [`Targets`](#targets) to failover to in order of preference. - `LoadBalancer` `(LoadBalancer: `) - Copy of the underlying `service-resolver` - [`LoadBalancer`](/docs/connect/config-entries/service-resolver#loadbalancer) field. + [`LoadBalancer`](/consul/docs/connect/config-entries/service-resolver#loadbalancer) field. If a `service-splitter` splits between services with differing `LoadBalancer` configuration the first hash-based load balancing policy is copied. @@ -202,7 +202,7 @@ A single node in the compiled discovery chain. - `Service` `(string)` - The service to query when resolving a list of service instances. - `ServiceSubset` `(string: )` - The - [subset](/docs/connect/config-entries/service-resolver#service-subsets) of + [subset](/consul/docs/connect/config-entries/service-resolver#service-subsets) of the service to resolve. - `Partition` `(string)` - The partition to use when resolving a list of service instances. @@ -213,11 +213,11 @@ A single node in the compiled discovery chain. - `Subset` `(ServiceResolverSubset)` - Copy of the underlying `service-resolver` - [`Subsets`](/docs/connect/config-entries/service-resolver#subsets) + [`Subsets`](/consul/docs/connect/config-entries/service-resolver#subsets) definition for this target. - `Filter` `(string: "")` - The - [filter expression](/api-docs/features/filtering) to be used for selecting + [filter expression](/consul/api-docs/features/filtering) to be used for selecting instances of the requested service. If empty all healthy instances are returned. @@ -228,7 +228,7 @@ A single node in the compiled discovery chain. be considered healthy. - `MeshGateway` `(MeshGatewayConfig)` - The [mesh gateway - configuration](/docs/connect/gateways/mesh-gateway#connect-proxy-configuration) + configuration](/consul/docs/connect/gateways/mesh-gateway#connect-proxy-configuration) to use when connecting to this target's service instances. - `Mode` `(string: "")` - One of `none`, `local`, or `remote`. @@ -236,7 +236,7 @@ A single node in the compiled discovery chain. - `External` `(bool: false)` - True if this target is outside of this consul cluster. - `ConnectTimeout` `(duration)` - Copy of the underlying `service-resolver` - [`ConnectTimeout`](/docs/connect/config-entries/service-resolver#connecttimeout) + [`ConnectTimeout`](/consul/docs/connect/config-entries/service-resolver#connecttimeout) field. If one is not defined the default of `5s` is returned. - `SNI` `(string)` - This value should be used as the @@ -246,4 +246,4 @@ A single node in the compiled discovery chain. - `Name` `(string)` - The unique name for this target for use when generating load balancer objects. This has a structure similar to [SNI](#sni), but will not be affected by SNI customizations such as - [`ExternalSNI`](/docs/connect/config-entries/service-defaults#externalsni). + [`ExternalSNI`](/consul/docs/connect/config-entries/service-defaults#externalsni). diff --git a/website/content/docs/connect/l7-traffic/index.mdx b/website/content/docs/connect/l7-traffic/index.mdx index 2845640ce6..c15c3656ed 100644 --- a/website/content/docs/connect/l7-traffic/index.mdx +++ b/website/content/docs/connect/l7-traffic/index.mdx @@ -11,7 +11,7 @@ description: >- Layer 7 traffic management allows operators to divide L7 traffic between different -[subsets](/docs/connect/config-entries/service-resolver#service-subsets) of +[subsets](/consul/docs/connect/config-entries/service-resolver#service-subsets) of service instances when using Connect. There are many ways you may wish to carve up a single datacenter's pool of @@ -22,9 +22,9 @@ carving out portions of the Consul catalog smaller than the level of a single service and configuring when that subset should receive traffic. -> **Note:** This feature is not compatible with the -[built-in proxy](/docs/connect/proxies/built-in), -[native proxies](/docs/connect/native), -and some [Envoy proxy escape hatches](/docs/connect/proxies/envoy#escape-hatch-overrides). +[built-in proxy](/consul/docs/connect/proxies/built-in), +[native proxies](/consul/docs/connect/native), +and some [Envoy proxy escape hatches](/consul/docs/connect/proxies/envoy#escape-hatch-overrides). ## Stages @@ -35,12 +35,12 @@ traffic. ![screenshot of L7 traffic visualization in the UI](/img/l7-routing/full.png) Each stage of this discovery process can be dynamically reconfigured via various -[configuration entries](/docs/agent/config-entries). When a configuration +[configuration entries](/consul/docs/agent/config-entries). When a configuration entry is missing, that stage will fall back on reasonable default behavior. ### Routing -A [`service-router`](/docs/connect/config-entries/service-router) config +A [`service-router`](/consul/docs/connect/config-entries/service-router) config entry kind is the first configurable stage. ![screenshot of service router in the UI](/img/l7-routing/Router.png) @@ -52,12 +52,12 @@ traffic to a different service or service subset. These config entries may only reference `service-splitter` or `service-resolver` entries. -[Examples](/docs/connect/config-entries/service-router#sample-config-entries) +[Examples](/consul/docs/connect/config-entries/service-router#sample-config-entries) can be found in the `service-router` documentation. ### Splitting -A [`service-splitter`](/docs/connect/config-entries/service-splitter) config +A [`service-splitter`](/consul/docs/connect/config-entries/service-splitter) config entry kind is the next stage after routing. ![screenshot of service splitter in the UI](/img/l7-routing/Splitter.png) @@ -79,12 +79,12 @@ union. For instance: --------------------- splitter[effective_B]: A_v1=25%, A_v2=25%, B=50% -[Examples](/docs/connect/config-entries/service-splitter#sample-config-entries) +[Examples](/consul/docs/connect/config-entries/service-splitter#sample-config-entries) can be found in the `service-splitter` documentation. ### Resolution -A [`service-resolver`](/docs/connect/config-entries/service-resolver) config +A [`service-resolver`](/consul/docs/connect/config-entries/service-resolver) config entry kind is the last stage. ![screenshot of service resolver in the UI](/img/l7-routing/Resolver.png) @@ -118,7 +118,7 @@ not intended to be a drop-in replacement currently. These config entries may only reference other `service-resolver` entries. -[Examples](/docs/connect/config-entries/service-resolver#sample-config-entries) +[Examples](/consul/docs/connect/config-entries/service-resolver#sample-config-entries) can be found in the `service-resolver` documentation. -> **Note:** `service-resolver` config entries kinds can function at L4 (unlike diff --git a/website/content/docs/connect/native/go.mdx b/website/content/docs/connect/native/go.mdx index 56ee2cd713..4c47bc315d 100644 --- a/website/content/docs/connect/native/go.mdx +++ b/website/content/docs/connect/native/go.mdx @@ -18,7 +18,7 @@ connections. For most Go applications, Connect can be natively integrated in just a single line of code excluding imports and struct initialization. In addition to this, please read and understand the -[overview of Connect-Native integrations](/docs/connect/native). +[overview of Connect-Native integrations](/consul/docs/connect/native). In particular, after integrating applications with Connect, they must declare that they accept Connect-based connections via their service definitions. @@ -176,7 +176,7 @@ the following specific limitations: - `.service[.].consul` to discover a healthy service instance for a given service. - `.query[.].consul` to discover an instance via - [Prepared Query](/api-docs/query). + [Prepared Query](/consul/api-docs/query). - The top-level domain _must_ be `.consul` even if your cluster has a custom `domain` configured for its DNS interface. This might be relaxed in the future. diff --git a/website/content/docs/connect/native/index.mdx b/website/content/docs/connect/native/index.mdx index bae584ca36..ffeb720f8b 100644 --- a/website/content/docs/connect/native/index.mdx +++ b/website/content/docs/connect/native/index.mdx @@ -9,12 +9,12 @@ description: >- ~> **Note:** The Native App Integration does not support many of the Connect service mesh features, and is not under active development. -The [Envoy proxy](/docs/connect/proxies/envoy) should be used for most production +The [Envoy proxy](/consul/docs/connect/proxies/envoy) should be used for most production environments. Applications can natively integrate with the Connect API to support accepting and establishing connections to other Connect services without the overhead of a -[proxy sidecar](/docs/connect/proxies). This option is especially useful +[proxy sidecar](/consul/docs/connect/proxies). This option is especially useful for applications that may be experiencing performance issues with the proxy sidecar deployment. This page will cover the high-level overview of integration, registering the service, etc. For language-specific examples, see @@ -26,7 +26,7 @@ can easily integrate with Connect. There is no custom protocol in use; any language that supports TLS can accept and establish Connect-based connections. -We currently provide an easy-to-use [Go integration](/docs/connect/native/go) +We currently provide an easy-to-use [Go integration](/consul/docs/connect/native/go) to assist with the getting the proper certificates, verifying connections, etc. We plan to add helper libraries for other languages in the future. However, without library support, it is still possible for any major language @@ -35,9 +35,9 @@ to integrate with Connect. ## Overview The primary work involved in natively integrating with Connect is -[acquiring the proper TLS certificate](/api-docs/agent/connect#service-leaf-certificate), -[verifying TLS certificates](/api-docs/agent/connect#certificate-authority-ca-roots), -and [authorizing inbound connections or requests](/api-docs/connect/intentions#list-matching-intentions). +[acquiring the proper TLS certificate](/consul/api-docs/agent/connect#service-leaf-certificate), +[verifying TLS certificates](/consul/api-docs/agent/connect#certificate-authority-ca-roots), +and [authorizing inbound connections or requests](/consul/api-docs/connect/intentions#list-matching-intentions). All of this is done using the Consul HTTP APIs linked above. @@ -48,33 +48,33 @@ an API call to verify the incoming client certificate. ![Native Integration Overview](/img/connect-native-overview.png) -> **Note:** This diagram depicts the simpler networking layer 4 (e.g. TCP) [integration -mechanism](/api-docs/agent/connect#authorize). +mechanism](/consul/api-docs/agent/connect#authorize). Details on the steps are below: - **Service discovery** - This is normal service discovery using Consul, a static IP, or any other mechanism. If you're using Consul DNS, the - [`.connect`](/docs/discovery/dns#connect-capable-service-lookups) + [`.connect`](/consul/docs/discovery/dns#connect-capable-service-lookups) syntax to find Connect-capable endpoints for a service. After service discovery, choose one address from the list of **service addresses**. - **Mutual TLS** - As a client, connect to the discovered service address over normal TLS. As part of the TLS connection, provide the - [service certificate](/api-docs/agent/connect#service-leaf-certificate) + [service certificate](/consul/api-docs/agent/connect#service-leaf-certificate) as the client certificate. Verify the remote certificate against the - [public CA roots](/api-docs/agent/connect#certificate-authority-ca-roots). + [public CA roots](/consul/api-docs/agent/connect#certificate-authority-ca-roots). As a client, if the connection is established then you've established a Connect-based connection and there are no further steps! - **Authorization** - As a server accepting connections, verify the client certificate against the [public CA - roots](/api-docs/agent/connect#certificate-authority-ca-roots). After verifying + roots](/consul/api-docs/agent/connect#certificate-authority-ca-roots). After verifying the certificate, parse some basic fields from it and use those to determine if the connection should be allowed. How this is done is dependent on the level of integration desired: - **Simple integration (TCP-only)** - Call the [authorizing - API](/api-docs/agent/connect#authorize) against the local agent. If this returns + API](/consul/api-docs/agent/connect#authorize) against the local agent. If this returns successfully, complete the TLS handshake and establish the connection. If authorization fails, close the connection. @@ -87,7 +87,7 @@ Details on the steps are below: - **Complete integration** - Like how the calls to acquire the leaf certificate and CA roots are expected to be done out of band and reused, so should the [intention match - API](/api-docs/connect/intentions#list-matching-intentions). With all of the + API](/consul/api-docs/connect/intentions#list-matching-intentions). With all of the relevant intentions cached for the destination, all enforcement operations can be done entirely by the service without calling any Consul APIs in the connection or request path. If the service is networking layer 7 (e.g. @@ -102,10 +102,10 @@ so that new connections are not disrupted. This can be done through Consul blocking queries (HTTP long polling) or through periodic polling. The API calls for -[acquiring a leaf TLS certificate](/api-docs/agent/connect#service-leaf-certificate) -and [reading CA roots](/api-docs/agent/connect#certificate-authority-ca-roots) +[acquiring a leaf TLS certificate](/consul/api-docs/agent/connect#service-leaf-certificate) +and [reading CA roots](/consul/api-docs/agent/connect#certificate-authority-ca-roots) both support -[blocking queries](/api-docs/features/blocking). By using blocking +[blocking queries](/consul/api-docs/features/blocking). By using blocking queries, an application can efficiently wait for an updated value. For example, the leaf certificate API will block until the certificate is near expiration or the signing certificates have changed and will issue and return a new @@ -114,7 +114,7 @@ certificate. In some languages, using blocking queries may not be simple. In that case, we still recommend using the blocking query parameters but with a very short `timeout` value set. Doing this is documented with -[blocking queries](/api-docs/features/blocking). The low timeout will +[blocking queries](/consul/api-docs/features/blocking). The low timeout will ensure the API responds quickly. We recommend that applications poll the certificate endpoints frequently, such as multiple times per minute. @@ -126,7 +126,7 @@ on certificate updates, this translates to only one TCP connection to the Consul server. Some language libraries such as the -[Go library](/docs/connect/native/go) automatically handle updating +[Go library](/consul/docs/connect/native/go) automatically handle updating and locally caching the certificates. ## Service Registration @@ -134,9 +134,9 @@ and locally caching the certificates. Connect-native applications must tell Consul that they support Connect natively. This enables the service to be returned as part of service discovery for Connect-capable services, used by other Connect-native applications -and client [proxies](/docs/connect/proxies). +and client [proxies](/consul/docs/connect/proxies). -This can be specified directly in the [service definition](/docs/discovery/services): +This can be specified directly in the [service definition](/consul/docs/discovery/services): ```json { diff --git a/website/content/docs/connect/nomad.mdx b/website/content/docs/connect/nomad.mdx index fc88d86c71..cd4849fbaf 100644 --- a/website/content/docs/connect/nomad.mdx +++ b/website/content/docs/connect/nomad.mdx @@ -10,7 +10,7 @@ description: >- Consul Connect can be used with [Nomad](https://www.nomadproject.io/) to provide secure service-to-service communication between Nomad jobs and task groups. Nomad is a simple, flexible scheduler and workload orchestrator. The ability to -use the [dynamic port](https://www.nomadproject.io/docs/job-specification/network#dynamic-ports) +use the [dynamic port](/nomad/docs/job-specification/network#dynamic-ports) feature of Nomad makes Connect reduces operational complexity. For more information @@ -18,12 +18,12 @@ about using Consul Connect with Nomad, select one of the following resources. For a step-by-step guide on using Consul Connect with Nomad: -- [Nomad Consul Connect Guide](https://www.nomadproject.io/docs/integrations/consul-connect) +- [Nomad Consul Connect Guide](/nomad/docs/integrations/consul-connect) For reference information about configuring Nomad jobs to use Consul Connect: -- [Nomad Job Specification - `connect`](https://www.nomadproject.io/docs/job-specification/connect) -- [Nomad Job Specification - `sidecar_service`](https://www.nomadproject.io/docs/job-specification/sidecar_service) -- [Nomad Job Specification - `sidecar_task`](https://www.nomadproject.io/docs/job-specification/sidecar_task) -- [Nomad Job Specification - `proxy`](https://www.nomadproject.io/docs/job-specification/proxy) -- [Nomad Job Specification - `upstreams`](https://www.nomadproject.io/docs/job-specification/upstreams) +- [Nomad Job Specification - `connect`](/nomad/docs/job-specification/connect) +- [Nomad Job Specification - `sidecar_service`](/nomad/docs/job-specification/sidecar_service) +- [Nomad Job Specification - `sidecar_task`](/nomad/docs/job-specification/sidecar_task) +- [Nomad Job Specification - `proxy`](/nomad/docs/job-specification/proxy) +- [Nomad Job Specification - `upstreams`](/nomad/docs/job-specification/upstreams) diff --git a/website/content/docs/connect/observability/access-logs.mdx b/website/content/docs/connect/observability/access-logs.mdx index e4dc81bda4..377b32b517 100644 --- a/website/content/docs/connect/observability/access-logs.mdx +++ b/website/content/docs/connect/observability/access-logs.mdx @@ -18,7 +18,7 @@ Consul supports access logs capture through Envoy proxies started through the [` ## Enable access logs -Access logs configurations are defined globally in the [`proxy-defaults`](/docs/connect/config-entries/proxy-defaults#accesslogs) configuration entry. +Access logs configurations are defined globally in the [`proxy-defaults`](/consul/docs/connect/config-entries/proxy-defaults#accesslogs) configuration entry. The following example is a minimal configuration for enabling access logs: @@ -108,7 +108,7 @@ Custom logs can be either JSON format or text format. You can format access logs in JSON so that you can parse them with Application Monitoring Platforms (APMs). -To use a custom access log, in the `proxy-defaults` configuration entry, set [`JSONFormat`](/docs/connect/config-entries/proxy-defaults#jsonformat) to the string representation of the desired JSON. +To use a custom access log, in the `proxy-defaults` configuration entry, set [`JSONFormat`](/consul/docs/connect/config-entries/proxy-defaults#jsonformat) to the string representation of the desired JSON. Nesting is supported. @@ -162,7 +162,7 @@ spec: ### Text format -To use a custom access log formatted in plaintext, in the `proxy-defaults` configuration entry, set [`TextFormat`](/docs/connect/config-entries/proxy-defaults#textformat) to the desired customized string. +To use a custom access log formatted in plaintext, in the `proxy-defaults` configuration entry, set [`TextFormat`](/consul/docs/connect/config-entries/proxy-defaults#textformat) to the desired customized string. New lines are automatically added to the end of the log to keep each access log on its own line in the output. @@ -205,7 +205,7 @@ spec: ## Kubernetes As part of its normal operation, the Envoy debugging logs for the `consul-dataplane`, `envoy`, or `envoy-sidecar` containers are written to `stderr`. -The access log [`Type`](/docs/connect/config-entries/proxy-defaults#type) is set to `stdout` by default for access logs when enabled. +The access log [`Type`](/consul/docs/connect/config-entries/proxy-defaults#type) is set to `stdout` by default for access logs when enabled. Use a log aggregating solution to separate the machine-readable access logs from the Envoy process debug logs. ## Write to a file diff --git a/website/content/docs/connect/observability/index.mdx b/website/content/docs/connect/observability/index.mdx index b56611dab8..3da463b389 100644 --- a/website/content/docs/connect/observability/index.mdx +++ b/website/content/docs/connect/observability/index.mdx @@ -17,14 +17,14 @@ to: - Define the upstreams for each of your services. If you are using Envoy as your sidecar proxy, you will need to [enable -gRPC](/docs/agent/config/config-files#grpc_port) on your client agents. To define the +gRPC](/consul/docs/agent/config/config-files#grpc_port) on your client agents. To define the metrics destination and service protocol you may want to enable [configuration -entries](/docs/agent/config/config-files#config_entries) and [centralized service -configuration](/docs/agent/config/config-files#enable_central_service_config). +entries](/consul/docs/agent/config/config-files#config_entries) and [centralized service +configuration](/consul/docs/agent/config/config-files#enable_central_service_config). ### Kubernetes If you are using Kubernetes, the Helm chart can simplify much of the configuration needed to enable observability. See -our [Kubernetes observability docs](/docs/k8s/connect/observability/metrics) for more information. +our [Kubernetes observability docs](/consul/docs/k8s/connect/observability/metrics) for more information. ### Metrics Destination @@ -39,13 +39,13 @@ config { } ``` -Find other possible metrics syncs in the [Connect Envoy documentation](/docs/connect/proxies/envoy#bootstrap-configuration). +Find other possible metrics syncs in the [Connect Envoy documentation](/consul/docs/connect/proxies/envoy#bootstrap-configuration). ### Service Protocol -You can specify the [service protocol](/docs/connect/config-entries/service-defaults#protocol) +You can specify the [service protocol](/consul/docs/connect/config-entries/service-defaults#protocol) in the `service-defaults` configuration entry. You can override it in the -[service registration](/docs/discovery/services). By default, proxies only give +[service registration](/consul/docs/discovery/services). By default, proxies only give you L4 metrics. This protocol allows proxies to handle requests at the right L7 protocol and emit richer L7 metrics. It also allows proxies to make per-request load balancing and routing decisions. @@ -53,6 +53,6 @@ load balancing and routing decisions. ### Service Upstreams You can set the upstream for each service using the proxy's -[`upstreams`](/docs/connect/registration/service-registration#upstreams) +[`upstreams`](/consul/docs/connect/registration/service-registration#upstreams) sidecar parameter, which can be defined in a service's [sidecar -registration](/docs/connect/registration/sidecar-service). +registration](/consul/docs/connect/registration/sidecar-service). diff --git a/website/content/docs/connect/observability/ui-visualization.mdx b/website/content/docs/connect/observability/ui-visualization.mdx index 5948949b62..b1a6f2a180 100644 --- a/website/content/docs/connect/observability/ui-visualization.mdx +++ b/website/content/docs/connect/observability/ui-visualization.mdx @@ -15,7 +15,7 @@ replacement for dedicated monitoring solutions, but rather as a quick overview of the state of a service and its connections within the Service Mesh. The topology visualization requires services to be using [Consul -Connect](/docs/connect) via [side-car proxies](/docs/connect/proxies). +Connect](/consul/docs/connect) via [side-car proxies](/consul/docs/connect/proxies). The visualization may optionally be configured to include a link to an external per-service dashboard. This is designed to provide convenient deep links to your @@ -36,7 +36,7 @@ Providers](#custom-metrics-providers). ## Kubernetes If running Consul in Kubernetes, the Helm chart can automatically configure Consul's UI to display topology -visualizations. See our [Kubernetes observability docs](/docs/k8s/connect/observability/metrics) for more information. +visualizations. See our [Kubernetes observability docs](/consul/docs/k8s/connect/observability/metrics) for more information. ## Configuring the UI To Display Metrics @@ -46,11 +46,11 @@ UI. If there are multiple clients with the UI enabled in a datacenter for redundancy these configurations must be added to all of them. We assume that the UI is already enabled by setting -[`ui_config.enabled`](/docs/agent/config/config-files#ui_config_enabled) to `true` in the +[`ui_config.enabled`](/consul/docs/agent/config/config-files#ui_config_enabled) to `true` in the agent's configuration file. To use the built-in Prometheus provider -[`ui_config.metrics_provider`](/docs/agent/config/config-files#ui_config_metrics_provider) +[`ui_config.metrics_provider`](/consul/docs/agent/config/config-files#ui_config_metrics_provider) must be set to `prometheus`. The UI must query the metrics provider through a proxy endpoint. This simplifies @@ -58,7 +58,7 @@ deployment where Prometheus is not exposed externally to UI user's browsers. To set this up, provide the URL that the _Consul agent_ should use to reach the Prometheus server in -[`ui_config.metrics_proxy.base_url`](/docs/agent/config/config-files#ui_config_metrics_proxy_base_url). +[`ui_config.metrics_proxy.base_url`](/consul/docs/agent/config/config-files#ui_config_metrics_proxy_base_url). For example in Kubernetes, the Prometheus helm chart by default installs a service named `prometheus-server` so each Consul agent can reach it on `http://prometheus-server` (using Kubernetes' DNS resolution). @@ -112,7 +112,7 @@ ui: --> **Note**: For more information on configuring the observability UI on Kubernetes, use this [reference](/docs/k8s/connect/observability/metrics). +-> **Note**: For more information on configuring the observability UI on Kubernetes, use this [reference](/consul/docs/k8s/connect/observability/metrics). ## Configuring Dashboard URLs @@ -123,7 +123,7 @@ service-specific dashboard in an external tool like [Grafana](https://grafana.com) or a hosted provider. To configure this, you must provide a URL template in the [agent configuration -file](/docs/agent/config/config-files#ui_config_dashboard_url_templates) for all agents that +file](/consul/docs/agent/config/config-files#ui_config_dashboard_url_templates) for all agents that have the UI enabled. The template is essentially the URL to the external dashboard, but can have placeholder values which will be replaced with the service name, namespace and datacenter where appropriate to allow deep-linking @@ -190,7 +190,7 @@ server: ~> **Note**: On Kubernetes, the Consul Server configuration set in the Helm config's -[`server.extraConfig`](/docs/k8s/helm#v-server-extraconfig) key must be specified +[`server.extraConfig`](/consul/docs/k8s/helm#v-server-extraconfig) key must be specified as JSON. The `{{` characters in the URL must be escaped using `{{ "{{" }}` so that Helm doesn't try to template them. @@ -297,7 +297,7 @@ namespace_prefix "" { It's typical for most authenticated users to have this level of access in Consul as it's required for viewing the catalog or discovering services. If you use a -[Single Sign-On integration](/docs/security/acl/auth-methods/oidc) (Consul +[Single Sign-On integration](/consul/docs/security/acl/auth-methods/oidc) (Consul Enterprise) users of the UI can be automatically issued an ACL token with the privileges above to be allowed access to the metrics through the proxy. @@ -658,12 +658,12 @@ ui_config { More than one JavaScript file may be specified in -[`metrics_provider_files`](/docs/agent/config/config-files#ui_config_metrics_provider_files) +[`metrics_provider_files`](/consul/docs/agent/config/config-files#ui_config_metrics_provider_files) and all will be served allowing flexibility if needed to include dependencies. Only one metrics provider can be configured and used at one time. The -[`metrics_provider_options_json`](/docs/agent/config/config-files#ui_config_metrics_provider_options_json) +[`metrics_provider_options_json`](/consul/docs/agent/config/config-files#ui_config_metrics_provider_options_json) field is an optional literal JSON object which is passed to the provider's `init` method at startup time. This allows configuring arbitrary parameters for the provider in config rather than hard coding them into the provider itself to @@ -672,7 +672,7 @@ make providers more reusable. The provider may fetch metrics directly from another source although in this case the agent will probably need to serve the correct CORS headers to prevent browsers from blocking these requests. These may be configured with -[`http_config.response_headers`](/docs/agent/config/config-files#response_headers). +[`http_config.response_headers`](/consul/docs/agent/config/config-files#response_headers). Alternatively, the provider may choose to use the [built-in metrics proxy](#metrics-proxy) to avoid cross domain issues or to inject additional diff --git a/website/content/docs/connect/proxies/built-in.mdx b/website/content/docs/connect/proxies/built-in.mdx index 9feeb98f15..87f6fb4292 100644 --- a/website/content/docs/connect/proxies/built-in.mdx +++ b/website/content/docs/connect/proxies/built-in.mdx @@ -9,7 +9,7 @@ description: >- ~> **Note:** The built-in proxy is not supported for production deployments. It does not support many of the Connect service mesh features, and is not under active development. -The [Envoy proxy](/docs/connect/proxies/envoy) should be used for production deployments. +The [Envoy proxy](/consul/docs/connect/proxies/envoy) should be used for production deployments. Consul comes with a built-in L4 proxy for testing and development with Consul Connect service mesh. @@ -54,8 +54,8 @@ All fields are optional with a reasonable default. - `bind_port` - The port the proxy will bind its _public_ mTLS listener to. If not provided, the agent will assign a random port from its - configured proxy port range specified by [`sidecar_min_port`](/docs/agent/config/config-files#sidecar_min_port) - and [`sidecar_max_port`](/docs/agent/config/config-files#sidecar_max_port). + configured proxy port range specified by [`sidecar_min_port`](/consul/docs/agent/config/config-files#sidecar_min_port) + and [`sidecar_max_port`](/consul/docs/agent/config/config-files#sidecar_max_port). - `local_service_address`- The `[address]:port` that the proxy should use to connect to the local application instance. By default @@ -77,7 +77,7 @@ All fields are optional with a reasonable default. - `upstreams`- **Deprecated** Upstreams are now specified in the `connect.proxy` definition. Upstreams specified in the opaque config map here will continue to work for compatibility but it's strongly recommended that - you move to using the higher level [upstream configuration](/docs/connect/registration/service-registration#upstream-configuration-reference). + you move to using the higher level [upstream configuration](/consul/docs/connect/registration/service-registration#upstream-configuration-reference). ## Proxy Upstream Config Key Reference diff --git a/website/content/docs/connect/proxies/envoy.mdx b/website/content/docs/connect/proxies/envoy.mdx index 10d2355361..337be509e7 100644 --- a/website/content/docs/connect/proxies/envoy.mdx +++ b/website/content/docs/connect/proxies/envoy.mdx @@ -57,7 +57,7 @@ Consul Dataplane is a feature introduced in Consul v1.14. Because each version o ## Getting Started To get started with Envoy and see a working example you can follow the [Using -Envoy with Connect](https://learn.hashicorp.com/tutorials/consul/service-mesh-with-envoy-proxy?utm_source=docs) tutorial. +Envoy with Connect](/consul/tutorials/developer-mesh/service-mesh-with-envoy-proxy?utm_source=docs) tutorial. ## Configuration @@ -190,7 +190,7 @@ The [Advanced Configuration](#advanced-configuration) section describes addition ### Bootstrap Envoy on Windows VMs -> Complete the [Connect Services on Windows Workloads to Consul Service Mesh tutorial](/consu/tutorials/consul-windows-workloads?utm_source=docs) to learn how to deploy Consul and use its service mesh on Windows VMs. +> Complete the [Connect Services on Windows Workloads to Consul Service Mesh tutorial](https://consul.io/consu/tutorials/consul-windows-workloads?utm_source=docs) to learn how to deploy Consul and use its service mesh on Windows VMs. If you are running Consul on a Windows VM, attempting to bootstrap Envoy with the `consul connect envoy` command returns the following output: diff --git a/website/content/docs/connect/proxies/index.mdx b/website/content/docs/connect/proxies/index.mdx index bb83041439..799daebd4e 100644 --- a/website/content/docs/connect/proxies/index.mdx +++ b/website/content/docs/connect/proxies/index.mdx @@ -20,16 +20,16 @@ the Connect protocol, you should configure all services to only accept connectio ~> **Deprecation Note:** Managed Proxies are a deprecated method for deploying sidecar proxies, and have been removed in Consul 1.6. See [managed proxy -deprecation](/docs/connect/proxies/managed-deprecated) for more +deprecation](/consul/docs/connect/proxies/managed-deprecated) for more information. If you are using managed proxies we strongly recommend that you switch service definitions for registering proxies. ## Dynamic Upstreams Require Native Integration If an application requires dynamic dependencies that are only available -at runtime, it must [natively integrate](/docs/connect/native) +at runtime, it must [natively integrate](/consul/docs/connect/native) with Connect. After natively integrating, the HTTP API or -[DNS interface](/docs/discovery/dns#connect-capable-service-lookups) +[DNS interface](/consul/docs/discovery/dns#connect-capable-service-lookups) can be used. !> Connect proxies do not currently support dynamic upstreams. diff --git a/website/content/docs/connect/proxies/integrate.mdx b/website/content/docs/connect/proxies/integrate.mdx index f61605dd68..20a203059d 100644 --- a/website/content/docs/connect/proxies/integrate.mdx +++ b/website/content/docs/connect/proxies/integrate.mdx @@ -18,7 +18,7 @@ The proxy you integrate must be able to accept inbound connections and/or establ Sidecar proxies may support L4 or L7 network functionality. L4 integration is simpler and adequate for securing all traffic. L4 treats all traffic as TCP, however, so advanced routing or metrics features are not supported. -Full L7 support is built on top of L4 support. An L7 proxy integration supports most or all of the L7 traffic routing features in Connect by dynamically configuring routing, retries, and other L7 features. The built-in proxy only supports L4, while [Envoy](/docs/connect/proxies/envoy) supports the full L7 feature set. +Full L7 support is built on top of L4 support. An L7 proxy integration supports most or all of the L7 traffic routing features in Connect by dynamically configuring routing, retries, and other L7 features. The built-in proxy only supports L4, while [Envoy](/consul/docs/connect/proxies/envoy) supports the full L7 feature set. Areas where the integration approach differs between L4 and L7 are identified in this topic. @@ -55,15 +55,15 @@ transport layer. -> **Note:** Some features, such as (local) rate limiting or max connections, are expected to be proxy-level configurations enforced separately when authorization calls are made. Proxies can enforce the configurations based on information about request rates and other states that should already be available. -The proxy can authorize the connection by either calling the [`/v1/agent/connect/authorize`](/api-docs/agent/connect) API endpoint or by querying the [intention match API](/api-docs/connect/intentions#list-matching-intentions) endpoint. +The proxy can authorize the connection by either calling the [`/v1/agent/connect/authorize`](/consul/api-docs/agent/connect) API endpoint or by querying the [intention match API](/consul/api-docs/connect/intentions#list-matching-intentions) endpoint. -The [`/v1/agent/connect/authorize`](/api-docs/agent/connect) endpoint should be called in the connection path for each received connection. +The [`/v1/agent/connect/authorize`](/consul/api-docs/agent/connect) endpoint should be called in the connection path for each received connection. If the local Consul agent is down or unresponsive, the success rate of new connections will be compromised. The agent uses locally-cached data to authorize the connection and typically responds in microseconds. As a result, the TLS handshake typically spans microseconds. ~> **Note:** This endpoint is only suitable for L4 (e.g., TCP) integration. The endpoint always treats intentions with `Permissions` defined (i.e., L7 criteria) as `deny` intentions during evaluation. -The proxy can query the [intention match API](/api-docs/connect/intentions#list-matching-intentions) endpoint on startup to retrieve a list of intentions that match the proxy destination. The matches should be stored in the native filter configuration of the proxy, such as RBAC for Envoy. +The proxy can query the [intention match API](/consul/api-docs/connect/intentions#list-matching-intentions) endpoint on startup to retrieve a list of intentions that match the proxy destination. The matches should be stored in the native filter configuration of the proxy, such as RBAC for Envoy. For performance and reliability reasons, querying the intention match API endpoint is the recommended method for implementing intention enforcement. The cached intentions should be consulted for each incoming connection (L4) or request (L7) to determine if the connection or request should be accepted or rejected. @@ -88,7 +88,7 @@ background. The leaf, roots, and intentions should be updated in the background by the proxy. The leaf cert, root cert, and intentions endpoints support [blocking -queries](/api-docs/features/blocking), which should be used to get near-immediate +queries](/consul/api-docs/features/blocking), which should be used to get near-immediate updates for root key rotations, new leaf certs before expiry, and intention changes. @@ -109,23 +109,23 @@ endpoint for a service and provide a client certificate from the ## Configuration Discovery -The [`/v1/agent/service/:service_id`](/api-docs/agent/service#get-service-configuration) +The [`/v1/agent/service/:service_id`](/consul/api-docs/agent/service#get-service-configuration) API endpoint enables any proxy to discover proxy configurations registered with a local service. This endpoint supports hash-based blocking, which enables long-polling for changes to the registration/configuration. Any changes to the registration/config will result in the new config being returned immediately. -Refer to the [built-in proxy](/docs/connect/proxies/built-in) for an example implementation. Using the Go SDK, the proxy calls the HTTP "pull" API via the `watch` package: [`consul/connect/proxy/config.go`]. +Refer to the [built-in proxy](/consul/docs/connect/proxies/built-in) for an example implementation. Using the Go SDK, the proxy calls the HTTP "pull" API via the `watch` package: [`consul/connect/proxy/config.go`]. The [discovery chain] for each upstream service should be fetched from the -[`/v1/discovery-chain/:service_id`](/api-docs/discovery-chain#read-compiled-discovery-chain) +[`/v1/discovery-chain/:service_id`](/consul/api-docs/discovery-chain#read-compiled-discovery-chain) API endpoint. This will return a compiled graph of configurations a sidecar needs for a particular upstream service. If you are only implementing L4 support in your proxy, set the -[`OverrideProtocol`](/api-docs/discovery-chain#overrideprotocol) value to `tcp` when +[`OverrideProtocol`](/consul/api-docs/discovery-chain#overrideprotocol) value to `tcp` when fetching the discovery chain so that L7 features, such as HTTP routing rules, are not returned. -For each [target](/docs/connect/l7-traffic/discovery-chain#targets) in the resulting +For each [target](/consul/docs/connect/l7-traffic/discovery-chain#targets) in the resulting discovery chain, a list of healthy, Connect-capable endpoints may be fetched from the [`/v1/health/connect/:service_id`] API endpoint as described in the [Service Discovery](#service-discovery) section. @@ -133,12 +133,12 @@ Discovery](#service-discovery) section. The remaining nodes in the chain include configurations that should be translated into the nearest equivalent for features, such as HTTP routing, connection timeouts, connection pool settings, rate limits, etc. See the full [discovery -chain] documentation and relevant [config entry](/docs/agent/config-entries) +chain] documentation and relevant [config entry](/consul/docs/agent/config-entries) documentation for details about supported configuration parameters. ### Service Discovery -Proxies can use Consul's [service discovery API](`/v1/health/connect/:service_id`) to return all available, Connect-capable endpoints for a given service. This endpoint supports a `cached` query parameter, which uses [agent caching](/api-docs/features/caching) to improve +Proxies can use Consul's [service discovery API](https://consul.io/%60/v1/health/connect/:service_id%60) to return all available, Connect-capable endpoints for a given service. This endpoint supports a `cached` query parameter, which uses [agent caching](/consul/api-docs/features/caching) to improve performance. The API package provides a [`UseCache`] query option to leverage caching. In addition to performance improvements, using the cache makes the mesh more resilient to Consul server outages. This is because the mesh "fails static" with the last known set of service instances still used, rather than errors on new connections. @@ -150,9 +150,9 @@ proxies are likely to find it easier to integrate by pulling the set of endpoints and maintaining it in local memory using blocking queries. Upstreams may be defined with the Prepared Query target type. These upstreams -should use Consul's [prepared query](/api-docs/query) API to determine a list of upstream endpoints for the service. Note that the `PreparedQuery` API does not support blocking, so proxies choosing to populate endpoints in memory will need to poll the endpoint at a suitable and, ideally, configurable frequency. +should use Consul's [prepared query](/consul/api-docs/query) API to determine a list of upstream endpoints for the service. Note that the `PreparedQuery` API does not support blocking, so proxies choosing to populate endpoints in memory will need to poll the endpoint at a suitable and, ideally, configurable frequency. --> **Long-term support for [`service-resolver`](/docs/connect/config-entries/service-resolver) configuration +-> **Long-term support for [`service-resolver`](/consul/docs/connect/config-entries/service-resolver) configuration entries**. The `service-resolver` configuration will completely replace prepared queries in future versions of Consul. In some instances, however, prepared queries are still used. ## Sidecar Instantiation @@ -163,8 +163,8 @@ systems, such as init, systemd, supervisord, etc. If deployed within a cluster scheduler (Kubernetes, Nomad), proxies should run as a sidecar container in the same namespace. -Proxies will use the [`CONSUL_HTTP_TOKEN`](/commands#consul_http_token) and -[`CONSUL_HTTP_ADDR`](/commands#consul_http_addr) environment variables to +Proxies will use the [`CONSUL_HTTP_TOKEN`](/consul/commands#consul_http_token) and +[`CONSUL_HTTP_ADDR`](/consul/commands#consul_http_addr) environment variables to contact Consul and fetch certificates. This occurs if the `CONSUL_HTTP_TOKEN` environment variable contains a Consul ACL token that has the necessary permissions to read configurations for that service. If you use the Go [`api` package], then @@ -195,24 +195,24 @@ $ consul connect proxy -sidecar-for "web" -token-file=/etc/consul.d/consul.token If TLS is enabled on Consul, you will also need to add the following environment variables _prior_ to starting the proxy: -- [`CONSUL_CACERT`](/commands#consul_cacert) -- [`CONSUL_CLIENT_CERT`](/commands#consul_client_cert) -- [`CONSUL_CLIENT_KEY`](/commands#consul_client_key) +- [`CONSUL_CACERT`](/consul/commands#consul_cacert) +- [`CONSUL_CLIENT_CERT`](/consul/commands#consul_client_cert) +- [`CONSUL_CLIENT_KEY`](/consul/commands#consul_client_key) -The `CONSUL_CACERT`, `CONSUL_CLIENT_CERT` and `CONSUL_CLIENT_KEY` can also be provided as CLI flags. Refer to the [`consul connect proxy` documentation](/commands/connect/proxy) for details. +The `CONSUL_CACERT`, `CONSUL_CLIENT_CERT` and `CONSUL_CLIENT_KEY` can also be provided as CLI flags. Refer to the [`consul connect proxy` documentation](/consul/commands/connect/proxy) for details. -The proxy service ID comes from the user. See [`consul connect envoy`](/commands/connect/envoy#examples) for an example. You can use the `-proxy-id` flag to specify the ID of the proxy service you have already registered with the local agent. +The proxy service ID comes from the user. See [`consul connect envoy`](/consul/commands/connect/envoy#examples) for an example. You can use the `-proxy-id` flag to specify the ID of the proxy service you have already registered with the local agent. Alternatively, you can start the service using the `-sidecar-for=` option. This option queries Consul for a proxy that is registered as a sidecar for the specified ``. If exactly one service associated with the proxy is returned, the ID will be used to start the proxy. Your controller only needs to accept `-proxy-id` as an argument; the Consul CLI will resolve the ID for the name specified in `-sidecar-for` flag. -[`/v1/agent/connect/ca/leaf/`]: /api-docs/agent/connect#service-leaf-certificate -[`/v1/agent/connect/ca/roots`]: /api-docs/agent/connect#certificate-authority-ca-roots +[`/v1/agent/connect/ca/leaf/`]: /consul/api-docs/agent/connect#service-leaf-certificate +[`/v1/agent/connect/ca/roots`]: /consul/api-docs/agent/connect#certificate-authority-ca-roots [`api` package]: https://github.com/hashicorp/consul/tree/main/api [`consul/connect/proxy/config.go`]: https://github.com/hashicorp/consul/blob/v1.8.3/connect/proxy/config.go#L187 [`consul/connect/tls.go`]: https://github.com/hashicorp/consul/blob/v1.8.3/connect/tls.go#L232-L237 -[discovery chain]: /docs/connect/l7-traffic/discovery-chain +[discovery chain]: /consul/docs/connect/l7-traffic/discovery-chain [`usecache`]: https://github.com/hashicorp/consul/blob/v1.8.3/api/api.go#L99-L102 -[protocol]: /docs/connect/config-entries/service-defaults#protocol +[protocol]: /consul/docs/connect/config-entries/service-defaults#protocol diff --git a/website/content/docs/connect/proxies/managed-deprecated.mdx b/website/content/docs/connect/proxies/managed-deprecated.mdx index 2f39cd3fc7..4ac7adeb3a 100644 --- a/website/content/docs/connect/proxies/managed-deprecated.mdx +++ b/website/content/docs/connect/proxies/managed-deprecated.mdx @@ -16,13 +16,13 @@ definition. !> **Consul 1.6.0 removes Managed Proxies completely.** This documentation is provided for prior versions only. You may consider using [sidecar service -registrations](/docs/connect/registration/sidecar-service) instead. +registrations](/consul/docs/connect/registration/sidecar-service) instead. Managed proxies have been deprecated since Consul 1.3 and have been fully removed in Consul 1.6. Anyone using Managed Proxies should aim to change their workflow as soon as possible to avoid issues with a later upgrade. -After transitioning away from all managed proxy usage, the `proxy` subdirectory inside [`data_dir`](/docs/agent/config/cli-flags#_data_dir) (specified in Consul config) can be deleted to remove extraneous configuration files and free up disk space. +After transitioning away from all managed proxy usage, the `proxy` subdirectory inside [`data_dir`](/consul/docs/agent/config/cli-flags#_data_dir) (specified in Consul config) can be deleted to remove extraneous configuration files and free up disk space. **new and known issues will not be fixed**. @@ -40,7 +40,7 @@ with other workloads. So the high implementation cost of building robust process supervision didn't actually benefit most real use-cases. Instead of this Connect 1.3.0 introduces the concept of [sidecar service -registrations](/docs/connect/registration/sidecar-service) which +registrations](/consul/docs/connect/registration/sidecar-service) which have almost all of the benefits of simpler configuration but without any of the additional process management complexity. As a result they can be used to simplify configuration in both container-based and realistic production @@ -53,7 +53,7 @@ page will document how they work in the interim. -> **Deprecation Note:** It's _strongly_ recommended you do not build anything using Managed proxies and consider using [sidecar service -registrations](/docs/connect/registration/sidecar-service) instead. +registrations](/consul/docs/connect/registration/sidecar-service) instead. Managed proxies are given a unique proxy-specific ACL token that allows read-only access to Connect @@ -77,7 +77,7 @@ via agent configuration files. They _cannot_ be registered via the HTTP API. And 2.) Managed proxies are not started at all if Consul is running as root. Both of these default configurations help prevent arbitrary process execution or privilege escalation. This behavior can be configured -[per-agent](/docs/agent/config). +[per-agent](/consul/docs/agent/config). ### Lifecycle @@ -101,7 +101,7 @@ to re-adopt them on restart. ### Minimal Configuration Managed proxies are configured within a -[service definition](/docs/discovery/services). The simplest possible +[service definition](/consul/docs/discovery/services). The simplest possible managed proxy configuration is an empty configuration. This enables the default managed proxy and starts a listener for that service: @@ -117,7 +117,7 @@ default managed proxy and starts a listener for that service: The listener is started on random port within the configured Connect port range. It can be discovered using the -[DNS interface](/docs/discovery/dns#connect-capable-service-lookups) +[DNS interface](/consul/docs/discovery/dns#connect-capable-service-lookups) or [Catalog API](#). In most cases, service-to-service communication is established by @@ -170,12 +170,12 @@ passed to the proxy instance. For full details of the additional configurable options available when using the built-in proxy see the [built-in proxy configuration -reference](/docs/connect/configuration). +reference](/consul/docs/connect/configuration). ### Prepared Query Upstreams The upstream destination may also be a -[prepared query](/api-docs/query). +[prepared query](/consul/api-docs/query). This allows complex service discovery behavior such as connecting to the nearest neighbor or filtering by tags. @@ -207,11 +207,11 @@ service. For full details of the additional configurable options available when using the built-in proxy see the [built-in proxy configuration -reference](/docs/connect/configuration). +reference](/consul/docs/connect/configuration). ### Custom Managed Proxy -[Custom proxies](/docs/connect/proxies/integrate) can also be +[Custom proxies](/consul/docs/connect/proxies/integrate) can also be configured to run as a managed proxy. To configure custom proxies, specify an alternate command to execute for the proxy: @@ -239,7 +239,7 @@ any arguments to execute. The "daemon" mode expects a proxy to run as a long-running, blocking process. It should not double-fork into the background. The custom proxy should retrieve its configuration (such as the port to run on) -via the [custom proxy integration APIs](/docs/connect/proxies/integrate). +via the [custom proxy integration APIs](/consul/docs/connect/proxies/integrate). The default proxy command can be changed at an agent-global level in the agent configuration. An example in HCL format is shown below. @@ -258,7 +258,7 @@ proxy command will use `my-proxy` instead of the default built-in proxy. The `config` key is an optional opaque JSON object which will be passed through to the proxy via the proxy configuration endpoint to allow any configuration options the proxy needs to be specified. See the [built-in proxy -configuration reference](/docs/connect/configuration) +configuration reference](/consul/docs/connect/configuration) for details of config options that can be passed when using the built-in proxy. ### Managed Proxy Logs @@ -273,6 +273,6 @@ level logs showing service discovery, certificate and authorization information. ~> **Note:** In `-dev` mode there is no `data_dir` unless one is explicitly configured so logging is disabled. You can access logs by providing the -[`-data-dir`](/docs/agent/config/cli-flags#_data_dir) CLI option. If a data dir is +[`-data-dir`](/consul/docs/agent/config/cli-flags#_data_dir) CLI option. If a data dir is configured, this will also cause proxy processes to stay running when the agent terminates as described in [Lifecycle](#lifecycle). diff --git a/website/content/docs/connect/registration/index.mdx b/website/content/docs/connect/registration/index.mdx index 379174e310..24c7a81251 100644 --- a/website/content/docs/connect/registration/index.mdx +++ b/website/content/docs/connect/registration/index.mdx @@ -8,11 +8,11 @@ description: >- # Service Mesh Proxy Overview To make Connect aware of proxies you will need to register them in a [service -definition](/docs/discovery/services), just like you would register any other service with Consul. This section outlines your options for registering Connect proxies, either using independent registrations, or in nested sidecar registrations. +definition](/consul/docs/discovery/services), just like you would register any other service with Consul. This section outlines your options for registering Connect proxies, either using independent registrations, or in nested sidecar registrations. ## Proxy Service Registration -To register proxies with independent proxy service registrations, you can define them in either in config files or via the API just like any other service. Learn more about all of the options you can define when registering your proxy service in the [proxy registration documentation](/docs/connect/registration/service-registration). +To register proxies with independent proxy service registrations, you can define them in either in config files or via the API just like any other service. Learn more about all of the options you can define when registering your proxy service in the [proxy registration documentation](/consul/docs/connect/registration/service-registration). ## Sidecar Service Registration @@ -20,4 +20,4 @@ To reduce the amount of boilerplate needed for a sidecar proxy, application service definitions may define an inline sidecar service block. This is an opinionated shorthand for a separate full proxy registration as described above. For a description of how to configure the sidecar proxy as well as the opinionated defaults, see the [sidecar service registrations -documentation](/docs/connect/registration/sidecar-service). +documentation](/consul/docs/connect/registration/sidecar-service). diff --git a/website/content/docs/connect/registration/service-registration.mdx b/website/content/docs/connect/registration/service-registration.mdx index fcfecf0c01..2bfe409b5b 100644 --- a/website/content/docs/connect/registration/service-registration.mdx +++ b/website/content/docs/connect/registration/service-registration.mdx @@ -89,7 +89,7 @@ Specify the following parameters in the `proxy` code block to configure a sideca * `local_service_port`: Integer value that specifies the port that the proxy should use to connect to the _local_ service instance. Refer to the [proxy parameters reference](#local-service-port) for details. * `local_service_address`: String value that specifies the IP address or hostname that the proxy should use to connect to the _local_ service. Refer to the [proxy parameters reference](#local-service-address) for details. -See [Sidecar Service Registration](/docs/connect/registration/sidecar-service) for additional information about configuring service mesh proxies as sidecars. +See [Sidecar Service Registration](/consul/docs/connect/registration/sidecar-service) for additional information about configuring service mesh proxies as sidecars. ### Complete Configuration Example @@ -173,14 +173,14 @@ You can configure the service mesh proxy to create listeners for upstream servic | `local_bind_socket_mode` | String value that specifies a Unix octal that configures file permissions for the socket. | Optional | None | | `destination_type` | String value that specifies the type of discovery query the proxy should use for finding service mesh instances. The following values are supported:
  • `service`: Queries for upstream `service` types.
  • `prepared_query`: Queries for upstream prepared queries.
    • | Optional | `service` | | `datacenter` | String value that specifies the datacenter to issue the discovery query to. | Optional | Defaults to the local datacenter. | -| `config` | Object value that specifies opaque configuration options that will be provided to the proxy instance for the upstream.
    Valid JSON objects are also supported.
    The `config` parameter can specify timeouts, retries, and other proxy-specific features for the given upstream.
    See the [built-in proxy configuration reference](/docs/connect/proxies/built-in#proxy-upstream-config-key-reference) for configuration options when using the built-in proxy.
    If using Envoy as a proxy, see [Envoy configuration reference](/docs/connect/proxies/envoy#proxy-upstream-config-options) | Optional | None | +| `config` | Object value that specifies opaque configuration options that will be provided to the proxy instance for the upstream.
    Valid JSON objects are also supported.
    The `config` parameter can specify timeouts, retries, and other proxy-specific features for the given upstream.
    See the [built-in proxy configuration reference](/consul/docs/connect/proxies/built-in#proxy-upstream-config-key-reference) for configuration options when using the built-in proxy.
    If using Envoy as a proxy, see [Envoy configuration reference](/consul/docs/connect/proxies/envoy#proxy-upstream-config-options) | Optional | None | | `mesh_gateway` | Object that defines the mesh gateway configuration for the proxy. Refer to the [Mesh Gateway Configuration Reference](#mesh-gateway-configuration-reference) for configuration details. | Optional | None | ### Upstream Configuration Examples Upstreams support multiple destination types. The following examples include information about each implementation. --> **Snake case**: The examples in this topic use `snake_case` because the syntax is supported in configuration files and API registrations. See [Service Definition Parameter Case](/docs/discovery/services#service-definition-parameter-case) for additional information. +-> **Snake case**: The examples in this topic use `snake_case` because the syntax is supported in configuration files and API registrations. See [Service Definition Parameter Case](/consul/docs/discovery/services#service-definition-parameter-case) for additional information. @@ -303,7 +303,7 @@ The following examples show additional configuration for transparent proxies. Added in v1.10.0. -> Note that `snake_case` is used here as it works in both [config file and API -registrations](/docs/discovery/services#service-definition-parameter-case). +registrations](/consul/docs/discovery/services#service-definition-parameter-case). #### Configure a proxy listener for outbound traffic on port 22500 @@ -329,7 +329,7 @@ registrations](/docs/discovery/services#service-definition-parameter-case). The following examples show all possible mesh gateway configurations. -> Note that `snake_case` is used here as it works in both [config file and API -registrations](/docs/discovery/services#service-definition-parameter-case). +registrations](/consul/docs/discovery/services#service-definition-parameter-case). #### Using a Local/Egress Gateway in the Local Datacenter @@ -387,7 +387,7 @@ non-Connect-enabled applications to contact an HTTP endpoint. Some examples include: exposing a `/metrics` path for Prometheus or `/healthz` for kubelet liveness checks. -> Note that `snake_case` is used here as it works in both [config file and API -registrations](/docs/discovery/services#service-definition-parameter-case). +registrations](/consul/docs/discovery/services#service-definition-parameter-case). #### Expose listeners in Envoy for HTTP and GRPC checks registered with the local Consul agent @@ -434,8 +434,8 @@ registrations](/docs/discovery/services#service-definition-parameter-case). - `checks` `(bool: false)` - If enabled, all HTTP and gRPC checks registered with the agent are exposed through Envoy. Envoy will expose listeners for these checks and will only accept connections originating from localhost or Consul's - [advertise address](/docs/agent/config/config-files#advertise). The port for these listeners are dynamically allocated from - [expose_min_port](/docs/agent/config/config-files#expose_min_port) to [expose_max_port](/docs/agent/config/config-files#expose_max_port). + [advertise address](/consul/docs/agent/config/config-files#advertise). The port for these listeners are dynamically allocated from + [expose_min_port](/consul/docs/agent/config/config-files#expose_min_port) to [expose_max_port](/consul/docs/agent/config/config-files#expose_max_port). This flag is useful when a Consul client cannot reach registered services over localhost. One example is when running Consul on Kubernetes, and Consul agents run in their own pods. - `paths` `array: []` - A list of paths to expose through Envoy. diff --git a/website/content/docs/connect/registration/sidecar-service.mdx b/website/content/docs/connect/registration/sidecar-service.mdx index 81f483e24b..adf5ef20f0 100644 --- a/website/content/docs/connect/registration/sidecar-service.mdx +++ b/website/content/docs/connect/registration/sidecar-service.mdx @@ -13,7 +13,7 @@ the same VM or running as a separate container in the same network namespace. To simplify the configuration experience when deploying a sidecar for a service instance, Consul 1.3 introduced a new field in the Connect block of the [service -definition](/docs/discovery/services). +definition](/consul/docs/discovery/services). The `connect.sidecar_service` field is a complete nested service definition on which almost any regular service definition field can be set. The exceptions are @@ -37,7 +37,7 @@ To register a service instance with a sidecar, all that's needed is: ``` This will register the `web` service as normal, but will also register another -[proxy service](/docs/connect/proxies) with defaults values used. +[proxy service](/consul/docs/connect/proxies) with defaults values used. The above expands out to be equivalent to the following explicit service definitions: @@ -110,9 +110,9 @@ overridden to customize the proxy configuration. ``` This example customizes the [proxy -upstreams](/docs/connect/registration/service-registration#upstream-configuration-reference) +upstreams](/consul/docs/connect/registration/service-registration#upstream-configuration-reference) and some [built-in proxy -configuration](/docs/connect/proxies/built-in). +configuration](/consul/docs/connect/proxies/built-in). ## Sidecar Service Defaults @@ -129,12 +129,12 @@ proxy. - `tags` - Defaults to the tags of the parent service. - `meta` - Defaults to the service metadata of the parent service. - `port` - Defaults to being auto-assigned from a configurable - range specified by [`sidecar_min_port`](/docs/agent/config/config-files#sidecar_min_port) - and [`sidecar_max_port`](/docs/agent/config/config-files#sidecar_max_port). + range specified by [`sidecar_min_port`](/consul/docs/agent/config/config-files#sidecar_min_port) + and [`sidecar_max_port`](/consul/docs/agent/config/config-files#sidecar_max_port). - `kind` - Defaults to `connect-proxy`. This can't be overridden currently. - `check`, `checks` - By default we add a TCP check on the local address and port for the proxy, and a [service alias - check](/docs/discovery/checks#alias) for the parent service. If either + check](/consul/docs/discovery/checks#alias) for the parent service. If either `check` or `checks` fields are set, only the provided checks are registered. - `proxy.destination_service_name` - Defaults to the parent service name. - `proxy.destination_service_id` - Defaults to the parent service ID. @@ -143,7 +143,7 @@ proxy. ## Limitations -Almost all fields in a [service definition](/docs/discovery/services) may be +Almost all fields in a [service definition](/consul/docs/discovery/services) may be set on the `connect.sidecar_service` except for the following: - `id` - Sidecar services get an ID assigned and it is an error to override @@ -154,7 +154,7 @@ set on the `connect.sidecar_service` except for the following: service. - `connect.sidecar_service` - Service definitions can't be nested recursively. - `connect.proxy` - (Deprecated) [Managed - proxies](/docs/connect/proxies/managed-deprecated) can't be defined on a + proxies](/consul/docs/connect/proxies/managed-deprecated) can't be defined on a sidecar. - `connect.native` - Currently the `kind` is fixed to `connect-proxy` and it's an error to register a `connect-proxy` that is also Connect-native. diff --git a/website/content/docs/connect/security.mdx b/website/content/docs/connect/security.mdx index 9711509da0..31fa331da6 100644 --- a/website/content/docs/connect/security.mdx +++ b/website/content/docs/connect/security.mdx @@ -10,9 +10,9 @@ description: >- Connect enables secure service-to-service communication over mutual TLS. This provides both in-transit data encryption as well as authorization. This page will document how to secure Connect. To try Connect locally, complete the -[Getting Started guide](https://learn.hashicorp.com/tutorials/consul/service-mesh?utm_source=docs) or for a full security model reference, -see the dedicated [Consul security model](/docs/security) page. When -setting up Connect in production, review this [tutorial](https://learn.hashicorp.com/tutorials/consul/service-mesh-production-checklist?utm_source=consul.io&utm_medium=docs). +[Getting Started guide](/consul/tutorials/kubernetes-deploy/service-mesh?utm_source=docs) or for a full security model reference, +see the dedicated [Consul security model](/consul/docs/security) page. When +setting up Connect in production, review this [tutorial](/consul/tutorials/developer-mesh/service-mesh-production-checklist?utm_source=consul.io&utm_medium=docs). Connect will function in any Consul configuration. However, unless the checklist below is satisfied, Connect is not providing the security guarantees it was @@ -20,7 +20,7 @@ built for. The checklist below can be incrementally adopted towards full security if you prefer to operate in less secure models initially. ~> **Warning**: The checklist below should not be considered exhaustive. Please -read and understand the [Consul security model](/docs/security) +read and understand the [Consul security model](/consul/docs/security) in depth to assess whether your deployment satisfies the security requirements of Consul. @@ -31,10 +31,10 @@ of Consul. Consul must be configured to use ACLs with a default deny policy. This forces all requests to have explicit anonymous access or provide an ACL token. The configuration also forces all service-to-service communication to be explicitly -allowed via an allow [intention](/docs/connect/intentions). +allowed via an allow [intention](/consul/docs/connect/intentions). To learn how to enable ACLs, please see the -[tutorial on ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production). +[tutorial on ACLs](/consul/tutorials/security/access-control-setup-production). **If ACLs are enabled but are in default allow mode**, then services will be able to communicate by default. Additionally, if a proper anonymous token @@ -52,7 +52,7 @@ to verify server authenticity with each server having a unique TLS certificate. affect Connect since requests must also always contain a valid ACL token. Clients calling Consul APIs should be forced over encrypted connections. -See the [Consul agent encryption page](/docs/security/encryption) to +See the [Consul agent encryption page](/consul/docs/security/encryption) to learn more about configuring agent encryption. **If encryption is not enabled**, a malicious actor can sniff network @@ -66,7 +66,7 @@ clients and servers should be protected from unauthorized access. This protection must be done outside of Consul via access control systems provided by your target operating system. -The [full Consul security model](/docs/security) explains the +The [full Consul security model](/consul/docs/security) explains the risk of unauthorized access for both client agents and server agents. In general, the blast radius of unauthorized access for client agent directories is much smaller than servers. However, both must be protected against @@ -75,8 +75,8 @@ unauthorized access. ### Prevent Non-Connect Traffic to Services For services that are using -[proxies](/docs/connect/proxies) -(are not [natively integrated](/docs/connect/native)), +[proxies](/consul/docs/connect/proxies) +(are not [natively integrated](/consul/docs/connect/native)), network access via their unencrypted listeners must be restricted to only the proxy. This requires at a minimum restricting the listener to bind to loopback only. More complex solutions may involve using @@ -91,7 +91,7 @@ mechanisms must be used. For developer or operator access to a service, we recommend using a local Connect proxy. This is documented in the -[development and debugging guide](/docs/connect/dev). +[development and debugging guide](/consul/docs/connect/dev). **If non-proxy traffic can communicate with the service**, this traffic will not be encrypted or authorized via Connect. @@ -111,6 +111,6 @@ We **strongly advise** only exposing the administration interface on a loopback address (default configuration) and restricting access to a subset of users. **If the administration interface is exposed externally**, for -example by specifying a routable [`-admin-bind`](/commands/connect/envoy#admin-bind) +example by specifying a routable [`-admin-bind`](/consul/commands/connect/envoy#admin-bind) address, it may be possible for a malicious actor to gain access to Envoy's configuration, or impact the service's availability within the cluster. diff --git a/website/content/docs/connect/transparent-proxy.mdx b/website/content/docs/connect/transparent-proxy.mdx index 293445a1b1..cf0b56c96e 100644 --- a/website/content/docs/connect/transparent-proxy.mdx +++ b/website/content/docs/connect/transparent-proxy.mdx @@ -40,12 +40,12 @@ Your network must meet the following environment and software requirements to us * Transparent proxy is available for Kubernetes environments. * Consul 1.10.0+ * Consul Helm chart 0.32.0+. If you want to use the Consul CNI plugin to redirect traffic, Helm chart 0.48.0+ is required. Refer to [Enable the Consul CNI plugin](#enable-the-consul-cni-plugin) for additional information. -* [Service intentions](/docs/connect/intentions) must be configured to allow communication between intended services. +* [Service intentions](/consul/docs/connect/intentions) must be configured to allow communication between intended services. * The `ip_tables` kernel module must be running on all worker nodes within a Kubernetes cluster. If you are using the `modprobe` Linux utility, for example, issue the following command: `$ modprobe ip_tables` -~> **Upgrading to a supported version**: Always follow the [proper upgrade path](/docs/upgrading/upgrade-specific/#transparent-proxy-on-kubernetes) when upgrading to a supported version of Consul, Consul on Kubernetes (`consul-k8s`), and the Consul Helm chart. +~> **Upgrading to a supported version**: Always follow the [proper upgrade path](/consul/docs/upgrading/upgrade-specific/#transparent-proxy-on-kubernetes) when upgrading to a supported version of Consul, Consul on Kubernetes (`consul-k8s`), and the Consul Helm chart. ## Configuration @@ -132,7 +132,7 @@ By default, Consul generates a `connect-inject init` container as part of the Ku Instead, you can enable the Consul container network interface (CNI) plugin to perform traffic redirection. Because the plugin is executed by the Kubernetes kubelet, it already has the elevated privileges necessary to configure the network. Additionally, you do not need to specify annotations that automatically overwrite Kubernetes HTTP health probes when the plugin is enabled (see [Overwrite Kubernetes HTTP health probes](#overwrite-kubernetes-http-health-probes)). -The Consul Helm chart installs the CNI plugin, but it is disabled by default. Refer to the [instructions for enabling the CNI plugin](/docs/k8s/installation/install#enable-the-consul-cni-plugin) in the Consul on Kubernetes installation documentation for additional information. +The Consul Helm chart installs the CNI plugin, but it is disabled by default. Refer to the [instructions for enabling the CNI plugin](/consul/docs/k8s/installation/install#enable-the-consul-cni-plugin) in the Consul on Kubernetes installation documentation for additional information. ### Traffic redirection @@ -144,7 +144,7 @@ Both mechanisms redirect all inbound and outbound traffic, but you can configure #### Exclude inbound ports -The [`consul.hashicorp.com/transparent-proxy-exclude-inbound-ports`](/docs/k8s/annotations-and-labels#consul-hashicorp-com-transparent-proxy-exclude-inbound-ports) annotation defines a comma-separated list of inbound ports to exclude from traffic redirection when running in transparent proxy mode. The port numbers are string data values. In the following example, services in the pod at port `8200` and `8201` are not redirected through the transparent proxy: +The [`consul.hashicorp.com/transparent-proxy-exclude-inbound-ports`](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-transparent-proxy-exclude-inbound-ports) annotation defines a comma-separated list of inbound ports to exclude from traffic redirection when running in transparent proxy mode. The port numbers are string data values. In the following example, services in the pod at port `8200` and `8201` are not redirected through the transparent proxy: @@ -159,7 +159,7 @@ The [`consul.hashicorp.com/transparent-proxy-exclude-inbound-ports`](/docs/k8s/a #### Exclude outbound ports -The [`consul.hashicorp.com/transparent-proxy-exclude-outbound-ports`](/docs/k8s/annotations-and-labels#consul-hashicorp-com-transparent-proxy-exclude-outbound-ports) annotation defines a comma-separated list of outbound ports to exclude from traffic redirection when running in transparent proxy mode. The port numbers are string data values. In the following example, services in the pod at port `8200` and `8201` are not redirected through the transparent proxy: +The [`consul.hashicorp.com/transparent-proxy-exclude-outbound-ports`](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-transparent-proxy-exclude-outbound-ports) annotation defines a comma-separated list of outbound ports to exclude from traffic redirection when running in transparent proxy mode. The port numbers are string data values. In the following example, services in the pod at port `8200` and `8201` are not redirected through the transparent proxy: @@ -175,7 +175,7 @@ The [`consul.hashicorp.com/transparent-proxy-exclude-outbound-ports`](/docs/k8s/ #### Exclude outbound CIDR blocks -The [`consul.hashicorp.com/transparent-proxy-exclude-outbound-cidrs`](/docs/k8s/annotations-and-labels#consul-hashicorp-com-transparent-proxy-exclude-outbound-cidrs) annotation +The [`consul.hashicorp.com/transparent-proxy-exclude-outbound-cidrs`](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-transparent-proxy-exclude-outbound-cidrs) annotation defines a comma-separated list of outbound CIDR blocks to exclude from traffic redirection when running in transparent proxy mode. The CIDR blocks are string data values. In the following example, services in the `3.3.3.3/24` IP range are not redirected through the transparent proxy: @@ -192,7 +192,7 @@ In the following example, services in the `3.3.3.3/24` IP range are not redirect #### Exclude user IDs -The [`consul.hashicorp.com/transparent-proxy-exclude-uids`](/docs/k8s/annotations-and-labels#consul-hashicorp-com-transparent-proxy-exclude-uids) annotation +The [`consul.hashicorp.com/transparent-proxy-exclude-uids`](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-transparent-proxy-exclude-uids) annotation defines a comma-separated list of additional user IDs to exclude from traffic redirection when running in transparent proxy mode. The user IDs are string data values. In the following example, services with the IDs `4444 ` and `44444 ` are not redirected through the transparent proxy: @@ -213,35 +213,35 @@ In the following example, services with the IDs `4444 ` and `44444 ` are not red By default, `connect-inject` is disabled. As a result, Consul on Kubernetes uses a mechanism for traffic redirection that interferes with [Kubernetes HTTP health probes](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/). This is because probes expect the kubelet to reach the application container on the probe's endpoint. Instead, traffic is redirected through the sidecar proxy. As a result, health probes return errors because the kubelet does not encrypt that traffic using a mesh proxy. -There are two methods for solving this issue. The first method is to set the `connectInject.transparentProxy.defaultOverwriteProbes` annotation to overwrite the Kubernetes HTTP health probes so that they point to the proxy. The second method is to [enable the Consul container network interface (CNI) plugin](#enable-the-consul-cni-plugin) to perform traffic redirection. Refer to the [Consul on Kubernetes installation instructions](/docs/k8s/installation/install) for additional information. +There are two methods for solving this issue. The first method is to set the `connectInject.transparentProxy.defaultOverwriteProbes` annotation to overwrite the Kubernetes HTTP health probes so that they point to the proxy. The second method is to [enable the Consul container network interface (CNI) plugin](#enable-the-consul-cni-plugin) to perform traffic redirection. Refer to the [Consul on Kubernetes installation instructions](/consul/docs/k8s/installation/install) for additional information. #### Overwrite Kubernetes HTTP health probes You can either include the `connectInject.transparentProxy.defaultOverwriteProbes` Helm value to your command or add the `consul.hashicorp.com/transparent-proxy-overwrite-probes` Kubernetes annotation to your pod configuration to overwrite health probes. -Refer to [Kubernetes Health Checks in Consul on Kubernetes](/docs/k8s/connect/health) for additional information. +Refer to [Kubernetes Health Checks in Consul on Kubernetes](/consul/docs/k8s/connect/health) for additional information. ### Dial services across Kubernetes cluster -If your [Consul servers are federated between Kubernetes clusters](/docs/k8s/deployment-configurations/multi-cluster/kubernetes), +If your [Consul servers are federated between Kubernetes clusters](/consul/docs/k8s/deployment-configurations/multi-cluster/kubernetes), then you must configure services in one Kubernetes cluster to explicitly dial a service in the datacenter of another Kubernetes cluster using the -[consul.hashicorp.com/connect-service-upstreams](/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) annotation. +[consul.hashicorp.com/connect-service-upstreams](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) annotation. The following example configures the service to dial an upstream service called `my-service` in datacenter `dc2` on port `1234`: ```yaml "consul.hashicorp.com/connect-service-upstreams": "my-service:1234:dc2" ``` -If your Consul cluster is deployed to a [single datacenter spanning multiple Kubernetes clusters](/docs/k8s/deployment-configurations/single-dc-multi-k8s), +If your Consul cluster is deployed to a [single datacenter spanning multiple Kubernetes clusters](/consul/docs/k8s/deployment-configurations/single-dc-multi-k8s), then you must configure services in one Kubernetes cluster to explicitly dial a service in another Kubernetes cluster using the -[consul.hashicorp.com/connect-service-upstreams](/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) annotation. +[consul.hashicorp.com/connect-service-upstreams](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) annotation. The following example configures the service to dial an upstream service called `my-service` in another Kubernetes cluster on port `1234`: ```yaml "consul.hashicorp.com/connect-service-upstreams": "my-service:1234" ``` -You do not need to configure services to explicitly dial upstream services if your Consul clusters are connected with a [peering connection](/docs/connect/cluster-peering). +You do not need to configure services to explicitly dial upstream services if your Consul clusters are connected with a [peering connection](/consul/docs/connect/cluster-peering). ## Usage @@ -251,7 +251,7 @@ The Kubernetes Service name must match the Consul service name to use KubeDNS. T Kubernetes annotation to the service pods. The annotation overrides the Consul service name. Consul configures redirection for each Pod bound to the Kubernetes Service using `iptables` rules. The rules redirect all inbound and outbound traffic through an inbound and outbound listener on the sidecar proxy. Consul configures the proxy to route traffic to the appropriate upstream services based on [service -intentions](/docs/connect/config-entries/service-intentions), which address the upstream services using KubeDNS. +intentions](/consul/docs/connect/config-entries/service-intentions), which address the upstream services using KubeDNS. In the following example, the Kubernetes service selects `sample-app` application Pods so that they can be reached within the mesh. @@ -273,10 +273,10 @@ spec: -Additional services can query the [KubeDNS](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/) at `sample-app.default.svc.cluster.local` to reach `sample-app`. If ACLs are enabled and configured with default `deny` policies, the configuration also requires a [`ServiceIntention`](/docs/connect/config-entries/service-intentions) to allow it to talk to `sample-app`. +Additional services can query the [KubeDNS](https://kubernetes.io/docs/concepts/services-networking/dns-pod-service/) at `sample-app.default.svc.cluster.local` to reach `sample-app`. If ACLs are enabled and configured with default `deny` policies, the configuration also requires a [`ServiceIntention`](/consul/docs/connect/config-entries/service-intentions) to allow it to talk to `sample-app`. ### Headless Services -For services that are not addressed using a virtual cluster IP, you must configure the upstream service using the [DialedDirectly](/docs/connect/config-entries/service-defaults#dialeddirectly) option. Then, use DNS to discover individual instance addresses and dial them through the transparent proxy. When this mode is enabled on the upstream, services present connect certificates for mTLS and intentions are enforced at the destination. +For services that are not addressed using a virtual cluster IP, you must configure the upstream service using the [DialedDirectly](/consul/docs/connect/config-entries/service-defaults#dialeddirectly) option. Then, use DNS to discover individual instance addresses and dial them through the transparent proxy. When this mode is enabled on the upstream, services present connect certificates for mTLS and intentions are enforced at the destination. Note that when dialing individual instances, Consul ignores the HTTP routing rules configured with configuration entries. The transparent proxy acts as a TCP proxy to the original destination IP address. diff --git a/website/content/docs/consul-vs-other/api-gateway-compare.mdx b/website/content/docs/consul-vs-other/api-gateway-compare.mdx index 126f027ff6..6fae646e12 100644 --- a/website/content/docs/consul-vs-other/api-gateway-compare.mdx +++ b/website/content/docs/consul-vs-other/api-gateway-compare.mdx @@ -9,8 +9,8 @@ description: >- **Examples**: Kong Gateway, Apigee, Mulesoft, Gravitee -The [Consul API Gateway](/docs/api-gateway) is an implementation of the [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/). Traditionally, API gateways are used for two things: _client traffic management_ and _API lifecycle management_. +The [Consul API Gateway](/consul/docs/api-gateway) is an implementation of the [Kubernetes Gateway API](https://gateway-api.sigs.k8s.io/). Traditionally, API gateways are used for two things: _client traffic management_ and _API lifecycle management_. -Client traffic management refers to an API gateway's role in controlling the point of entry for public traffic into a given environment, also known as _managing north-south traffic_. The Consul API Gateway is deployed alongside Consul service mesh and is responsible for routing inbound client requests to the mesh based on defined routes. For a full list of supported traffic management features, refer to the [Consul API Gateway documentation](/docs/api-gateway). +Client traffic management refers to an API gateway's role in controlling the point of entry for public traffic into a given environment, also known as _managing north-south traffic_. The Consul API Gateway is deployed alongside Consul service mesh and is responsible for routing inbound client requests to the mesh based on defined routes. For a full list of supported traffic management features, refer to the [Consul API Gateway documentation](/consul/docs/api-gateway). API lifecycle management refers to how application developers use an API gateway to deploy, iterate, and manage versions of an API. At this time, the Consul API Gateway does not support API lifecycle management. diff --git a/website/content/docs/consul-vs-other/dns-tools-compare.mdx b/website/content/docs/consul-vs-other/dns-tools-compare.mdx index 558e7f2020..6aab144066 100644 --- a/website/content/docs/consul-vs-other/dns-tools-compare.mdx +++ b/website/content/docs/consul-vs-other/dns-tools-compare.mdx @@ -10,7 +10,7 @@ description: >- **Examples**: NS1, AWS Route53, AzureDNS, Cloudflare DNS -Consul was originally designed as a centralized service registry for any cloud environment that dynamically tracks services as they are added, changed, or removed within a compute infrastructure. Consul maintains a catalog of these registered services and their attributes, such as IP addresses or service name. For more information, refer to [What is Service Discovery?](/docs/concepts/service-discovery). +Consul was originally designed as a centralized service registry for any cloud environment that dynamically tracks services as they are added, changed, or removed within a compute infrastructure. Consul maintains a catalog of these registered services and their attributes, such as IP addresses or service name. For more information, refer to [What is Service Discovery?](/consul/docs/concepts/service-discovery). -As a result, Consul can also provide basic DNS functionality, including [lookups, alternate domains, and access controls](/docs/discovery/dns). Since Consul is platform agnostic, you can retrieve service information across both cloud and on-premises data centers. Consul does not natively support some advanced DNS capabilities, such as filters or advanced routing logic. However, you can integrate Consul with existing DNS solutions, such as [NS1](https://help.ns1.com/hc/en-us/articles/360039417093-NS1-Consul-Integration-Overview) and [DNSimple](https://blog.dnsimple.com/2022/05/consul-integration/), to support these advanced capabilities. +As a result, Consul can also provide basic DNS functionality, including [lookups, alternate domains, and access controls](/consul/docs/discovery/dns). Since Consul is platform agnostic, you can retrieve service information across both cloud and on-premises data centers. Consul does not natively support some advanced DNS capabilities, such as filters or advanced routing logic. However, you can integrate Consul with existing DNS solutions, such as [NS1](https://help.ns1.com/hc/en-us/articles/360039417093-NS1-Consul-Integration-Overview) and [DNSimple](https://blog.dnsimple.com/2022/05/consul-integration/), to support these advanced capabilities. diff --git a/website/content/docs/consul-vs-other/index.mdx b/website/content/docs/consul-vs-other/index.mdx index b20e9df3de..26901a3db4 100644 --- a/website/content/docs/consul-vs-other/index.mdx +++ b/website/content/docs/consul-vs-other/index.mdx @@ -9,7 +9,7 @@ description: >- HashiCorp Consul is a service networking platform that encompasses multiple capabilities to secure and simplify network service management. These capabilities include service mesh, service discovery, configuration management, and API gateway functionality. While competing products offer a few of these core capabilities, Consul is developed to address all four. The topics in this section provide a general overview of how Consul’s capabilities compare to some other tools on the market. Visit the following pages to read more about how: -- [Consul compares with other service meshes](/docs/consul-vs-other/service-mesh-compare) -- [Consul compares with other DNS tools](/docs/consul-vs-other/dns-tools-compare) -- [Consul compares with other configuration management tools](/docs/consul-vs-other/config-management-compare) -- [Consul compares with other API Gateways](/docs/consul-vs-other/api-gateway-compare) +- [Consul compares with other service meshes](/consul/docs/consul-vs-other/service-mesh-compare) +- [Consul compares with other DNS tools](/consul/docs/consul-vs-other/dns-tools-compare) +- [Consul compares with other configuration management tools](/consul/docs/consul-vs-other/config-management-compare) +- [Consul compares with other API Gateways](/consul/docs/consul-vs-other/api-gateway-compare) diff --git a/website/content/docs/discovery/checks.mdx b/website/content/docs/discovery/checks.mdx index a1391c2df7..bf5fece429 100644 --- a/website/content/docs/discovery/checks.mdx +++ b/website/content/docs/discovery/checks.mdx @@ -11,7 +11,7 @@ One of the primary roles of the agent is management of system-level and applicat checks. A health check is considered to be application-level if it is associated with a service. If not associated with a service, the check monitors the health of the entire node. -Review the [health checks tutorial](https://learn.hashicorp.com/tutorials/consul/service-registration-health-checks) +Review the [health checks tutorial](/consul/tutorials/developer-discovery/service-registration-health-checks) to get a more complete example on how to leverage health check capabilities in Consul. A check is defined in a configuration file or added at runtime over the HTTP interface. Checks @@ -54,12 +54,12 @@ There are severeal types of checks: There are three ways to register a service with health checks: 1. Start or reload a Consul agent with a service definition file in the - [agent's configuration directory](/docs/agent#configuring-consul-agents). + [agent's configuration directory](/consul/docs/agent#configuring-consul-agents). 1. Call the - [`/agent/service/register`](/api-docs/agent/service#register-service) + [`/agent/service/register`](/consul/api-docs/agent/service#register-service) HTTP API endpoint to register the service. 1. Use the - [`consul services register`](/commands/services/register) + [`consul services register`](/consul/commands/services/register) CLI command to register the service. When a service is registered using the HTTP API endpoint or CLI command, @@ -71,8 +71,8 @@ This section describes the available types of health checks you can use to automatically monitor the health of a service instance or node. -> **To manually mark a service unhealthy:** Use the maintenance mode - [CLI command](/commands/maint) or - [HTTP API endpoint](/api-docs/agent#enable-maintenance-mode) + [CLI command](/consul/commands/maint) or + [HTTP API endpoint](/consul/api-docs/agent#enable-maintenance-mode) to temporarily remove one or all service instances on a node from service discovery DNS and HTTP API query results. @@ -96,10 +96,10 @@ Script checks are not enabled by default. To enable a Consul agent to perform script checks, use one of the following agent configuration options: -- [`enable_local_script_checks`](/docs/agent/config/cli-flags#_enable_local_script_checks): +- [`enable_local_script_checks`](/consul/docs/agent/config/cli-flags#_enable_local_script_checks): Enable script checks defined in local config files. Script checks registered using the HTTP API are not allowed. -- [`enable_script_checks`](/docs/agent/config/cli-flags#_enable_script_checks): +- [`enable_script_checks`](/consul/docs/agent/config/cli-flags#_enable_script_checks): Enable script checks no matter how they are registered. ~> **Security Warning:** @@ -148,7 +148,7 @@ A check script's exit code is used to determine the health check status: Any output of the script is captured and made available in the `Output` field of checks included in HTTP API responses, -as in this example from the [local service health endpoint](/api-docs/agent/service#by-name-json). +as in this example from the [local service health endpoint](/consul/api-docs/agent/service#by-name-json). ### HTTP check @@ -355,17 +355,17 @@ This mechanism relies on the application to directly report its health. For example, a healthy app can periodically `PUT` a status update to the HTTP endpoint. Then, if the app is disrupted and unable to perform this update before the TTL expires, the health check enters the `critical` state. -The endpoints used to update health information for a given check are: [pass](/api-docs/agent/check#ttl-check-pass), -[warn](/api-docs/agent/check#ttl-check-warn), [fail](/api-docs/agent/check#ttl-check-fail), -and [update](/api-docs/agent/check#ttl-check-update). TTL checks also persist their +The endpoints used to update health information for a given check are: [pass](/consul/api-docs/agent/check#ttl-check-pass), +[warn](/consul/api-docs/agent/check#ttl-check-warn), [fail](/consul/api-docs/agent/check#ttl-check-fail), +and [update](/consul/api-docs/agent/check#ttl-check-update). TTL checks also persist their last known status to disk. This persistence allows the Consul agent to restore the last known status of the check across agent restarts. Persisted check status is valid through the end of the TTL from the time of the last check. To manually mark a service unhealthy, it is far more convenient to use the maintenance mode -[CLI command](/commands/maint) or -[HTTP API endpoint](/api-docs/agent#enable-maintenance-mode) +[CLI command](/consul/commands/maint) or +[HTTP API endpoint](/consul/api-docs/agent#enable-maintenance-mode) rather than a TTL health check with arbitrarily high `ttl`. The following service definition file snippet is an example @@ -413,11 +413,11 @@ Docker checks are not enabled by default. To enable a Consul agent to perform Docker checks, use one of the following agent configuration options: -- [`enable_local_script_checks`](/docs/agent/config/cli-flags#_enable_local_script_checks): +- [`enable_local_script_checks`](/consul/docs/agent/config/cli-flags#_enable_local_script_checks): Enable script checks defined in local config files. Script checks registered using the HTTP API are not allowed. -- [`enable_script_checks`](/docs/agent/config/cli-flags#_enable_script_checks): +- [`enable_script_checks`](/consul/docs/agent/config/cli-flags#_enable_script_checks): Enable script checks no matter how they are registered. !> **Security Warning:** @@ -586,7 +586,7 @@ node or service, the check state is set to `critical`. For the blocking query, the check uses the ACL token set on the service or check definition. If no ACL token is set in the service or check definition, the blocking query uses the agent's default ACL token -([`acl.tokens.default`](/docs/agent/config/config-files#acl_tokens_default)). +([`acl.tokens.default`](/consul/docs/agent/config/config-files#acl_tokens_default)). ~> **Configuration info**: The alias check configuration expects the alias to be registered on the same agent as the one you are aliasing. If the service is @@ -622,7 +622,7 @@ check = { This section covers some of the most common options for check definitions. For a complete list of all check options, refer to the -[Register Check HTTP API endpoint documentation](/api-docs/agent/check#json-request-body-schema). +[Register Check HTTP API endpoint documentation](/consul/api-docs/agent/check#json-request-body-schema). -> **Casing for check options:** The correct casing for an option depends on whether the check is defined in @@ -687,7 +687,7 @@ For a complete list of all check options, refer to the - `token` `(string: "")` - Specifies an ACL token used for any interaction with the catalog for the check, including - [anti-entropy syncs](/docs/architecture/anti-entropy) and deregistration. + [anti-entropy syncs](/consul/docs/architecture/anti-entropy) and deregistration. For alias checks, this token is used if a remote blocking query is necessary to watch the state of the aliased node or service. @@ -821,7 +821,7 @@ provided by the node will remain unchanged. ## Agent certificates for TLS checks -The [enable_agent_tls_for_checks](/docs/agent/config/config-files#enable_agent_tls_for_checks) +The [enable_agent_tls_for_checks](/consul/docs/agent/config/config-files#enable_agent_tls_for_checks) agent configuration option can be utilized to have HTTP or gRPC health checks to use the agent's credentials when configured for TLS. diff --git a/website/content/docs/discovery/dns.mdx b/website/content/docs/discovery/dns.mdx index 93074df540..90038ae295 100644 --- a/website/content/docs/discovery/dns.mdx +++ b/website/content/docs/discovery/dns.mdx @@ -19,21 +19,21 @@ are located in the `us-east-1` datacenter, and have no failing health checks. It's that simple! There are a number of configuration options that are important for the DNS interface, -specifically [`client_addr`](/docs/agent/config/config-files#client_addr),[`ports.dns`](/docs/agent/config/config-files#dns_port), -[`recursors`](/docs/agent/config/config-files#recursors),[`domain`](/docs/agent/config/config-files#domain), -[`alt_domain`](/docs/agent/config/config-files#alt_domain), and [`dns_config`](/docs/agent/config/config-files#dns_config). +specifically [`client_addr`](/consul/docs/agent/config/config-files#client_addr),[`ports.dns`](/consul/docs/agent/config/config-files#dns_port), +[`recursors`](/consul/docs/agent/config/config-files#recursors),[`domain`](/consul/docs/agent/config/config-files#domain), +[`alt_domain`](/consul/docs/agent/config/config-files#alt_domain), and [`dns_config`](/consul/docs/agent/config/config-files#dns_config). By default, Consul will listen on 127.0.0.1:8600 for DNS queries in the `consul.` domain, without support for further DNS recursion. Please consult the -[documentation on configuration options](/docs/agent/config), +[documentation on configuration options](/consul/docs/agent/config), specifically the configuration items linked above, for more details. There are a few ways to use the DNS interface. One option is to use a custom DNS resolver library and point it at Consul. Another option is to set Consul as the DNS server for a node and provide a -[`recursors`](/docs/agent/config/config-files#recursors) configuration so that non-Consul queries +[`recursors`](/consul/docs/agent/config/config-files#recursors) configuration so that non-Consul queries can also be resolved. The last method is to forward all queries for the "consul." domain to a Consul agent from the existing DNS server. Review the -[DNS Forwarding tutorial](https://learn.hashicorp.com/tutorials/consul/dns-forwarding?utm_source=docs) for examples. +[DNS Forwarding tutorial](/consul/tutorials/networking/dns-forwarding?utm_source=docs) for examples. You can experiment with Consul's DNS server on the command line using tools such as `dig`: @@ -117,7 +117,7 @@ A service lookup is used to query for service providers. Service queries support two lookup methods: standard and strict [RFC 2782](https://tools.ietf.org/html/rfc2782). By default, SRV weights are all set at 1, but changing weights is supported using the -`Weights` attribute of the [service definition](/docs/discovery/services). +`Weights` attribute of the [service definition](/consul/docs/discovery/services). Note that DNS is limited in size per request, even when performing DNS TCP queries. @@ -235,7 +235,7 @@ Again, note that the SRV record returns the port of the service as well as its I #### SRV response for hosts in the .addr subdomain -If a service registered to Consul has an explicit IP [`address`](/api-docs/agent/service#address) +If a service registered to Consul has an explicit IP [`address`](/consul/api-docs/agent/service#address) or tagged address(es) defined on the service registration, the hostname returned in the target field of the answer section for the DNS SRV query for the service will be in the format of `.addr..consul`. @@ -387,7 +387,7 @@ you can use the following query formats specify namespace but not partition: - **Deprecated in Consul 1.11:** Specify namespace without a datacenter, which requires that DNS queries are addressed to a Consul agent with - [`dns_config.prefer_namespace`](/docs/agent/config/config-files#dns_prefer_namespace) + [`dns_config.prefer_namespace`](/consul/docs/agent/config/config-files#dns_prefer_namespace) set to `true`: ```text @@ -414,11 +414,11 @@ The `datacenter` is optional, and if not provided, the datacenter of this Consul agent is assumed. The `query name or id` is the given name or ID of an existing -[Prepared Query](/api-docs/query). These behave like standard service +[Prepared Query](/consul/api-docs/query). These behave like standard service queries but provide a much richer set of features, such as filtering by multiple tags and automatically failing over to look for services in remote datacenters if no healthy nodes are available in the local datacenter. Consul 0.6.4 and later also -added support for [prepared query templates](/api-docs/query#prepared-query-templates) +added support for [prepared query templates](/consul/api-docs/query#prepared-query-templates) which can match names using a prefix match, allowing one template to apply to potentially many services. @@ -435,20 +435,20 @@ To find Connect-capable services: .connect. ``` -This will find all [Connect-capable](/docs/connect) +This will find all [Connect-capable](/consul/docs/connect) endpoints for the given `service`. A Connect-capable endpoint may be both a proxy for a service or a natively integrated Connect application. The DNS interface does not differentiate the two. -Most services will use a [proxy](/docs/connect/proxies) that handles +Most services will use a [proxy](/consul/docs/connect/proxies) that handles service discovery automatically and therefore won't use this DNS format. -This DNS format is primarily useful for [Connect-native](/docs/connect/native) +This DNS format is primarily useful for [Connect-native](/consul/docs/connect/native) applications. This endpoint currently only finds services within the same datacenter and doesn't support tags. This DNS interface will be expanded over time. If you need more complex behavior, please use the -[catalog API](/api-docs/catalog). +[catalog API](/consul/api-docs/catalog). ### Service Virtual IP Lookups @@ -458,13 +458,13 @@ To find the unique virtual IP allocated for a service: .virtual[.]. ``` -This will return the unique virtual IP for any [Connect-capable](/docs/connect) +This will return the unique virtual IP for any [Connect-capable](/consul/docs/connect) service. Each Connect service has a virtual IP assigned to it by Consul - this is used -by sidecar proxies for the [Transparent Proxy](/docs/connect/transparent-proxy) feature. +by sidecar proxies for the [Transparent Proxy](/consul/docs/connect/transparent-proxy) feature. The peer name is an optional part of the FQDN, and it is used to query for the virtual IP of a service imported from that peer. -The virtual IP is also added to the service's [Tagged Addresses](/docs/discovery/services#tagged-addresses) +The virtual IP is also added to the service's [Tagged Addresses](/consul/docs/discovery/services#tagged-addresses) under the `consul-virtual` tag. #### Service Virtual IP Lookups for Consul Enterprise @@ -489,13 +489,13 @@ To find ingress-enabled services: .ingress. ``` -This will find all [ingress gateway](/docs/connect/gateways/ingress-gateway) +This will find all [ingress gateway](/consul/docs/connect/gateways/ingress-gateway) endpoints for the given `service`. This endpoint currently only finds services within the same datacenter and doesn't support tags. This DNS interface will be expanded over time. If you need more complex behavior, please use the -[catalog API](/api-docs/catalog). +[catalog API](/consul/api-docs/catalog). ### UDP Based DNS Queries @@ -507,15 +507,15 @@ are not truncated. ## Alternative Domain By default, Consul responds to DNS queries in the `consul` domain, -but you can set a specific domain for responding to DNS queries by configuring the [`domain`](/docs/agent/config/config-files#domain) parameter. +but you can set a specific domain for responding to DNS queries by configuring the [`domain`](/consul/docs/agent/config/config-files#domain) parameter. In some instances, Consul may need to respond to queries in more than one domain, such as during a DNS migration or to distinguish between internal and external queries. Consul versions 1.5.2+ can be configured to respond to DNS queries on an alternative domain -through the [`alt_domain`](/docs/agent/config/config-files#alt_domain) agent configuration +through the [`alt_domain`](/consul/docs/agent/config/config-files#alt_domain) agent configuration option. As of Consul versions 1.11.0+, Consul's DNS response will use the same domain as was used in the query; -in prior versions, the response may use the primary [`domain`](/docs/agent/config/config-files#domain) no matter which +in prior versions, the response may use the primary [`domain`](/consul/docs/agent/config/config-files#domain) no matter which domain was used in the query. In the following example, the `alt_domain` parameter is set to `test-domain`: @@ -543,7 +543,7 @@ machine.node.dc1.test-domain. 0 IN TXT "consul-network-segment=" ``` -> **PTR queries:** Responses to PTR queries (`.in-addr.arpa.`) will always use the -[primary domain](/docs/agent/config/config-files#domain) (not the alternative domain), +[primary domain](/consul/docs/agent/config/config-files#domain) (not the alternative domain), as there is no way for the query to specify a domain. ## Caching @@ -551,28 +551,28 @@ as there is no way for the query to specify a domain. By default, all DNS results served by Consul set a 0 TTL value. This disables caching of DNS results. However, there are many situations in which caching is desirable for performance and scalability. This is discussed more in the tutorial -for [DNS caching](https://learn.hashicorp.com/tutorials/consul/dns-caching). +for [DNS caching](/consul/tutorials/networking/dns-caching). ## WAN Address Translation By default, Consul DNS queries will return a node's local address, even when being queried from a remote datacenter. If you need to use a different address to reach a node from outside its datacenter, you can configure this behavior -using the [`advertise-wan`](/docs/agent/config/cli-flags#_advertise-wan) and -[`translate_wan_addrs`](/docs/agent/config/config-files#translate_wan_addrs) configuration +using the [`advertise-wan`](/consul/docs/agent/config/cli-flags#_advertise-wan) and +[`translate_wan_addrs`](/consul/docs/agent/config/config-files#translate_wan_addrs) configuration options. ## DNS with ACLs In order to use the DNS interface when -[Access Control Lists (ACLs)](/docs/security/acl) +[Access Control Lists (ACLs)](/consul/docs/security/acl) are enabled, you must first create ACL tokens with the necessary policies. Consul agents resolve DNS requests using one of the preconfigured tokens below, listed in order of precedence: -1. The agent's [`default` token](/docs/agent/config/config-files#acl_tokens_default). -2. The built-in [`anonymous` token](/docs/security/acl/acl-tokens#built-in-tokens). +1. The agent's [`default` token](/consul/docs/agent/config/config-files#acl_tokens_default). +2. The built-in [`anonymous` token](/consul/docs/security/acl/acl-tokens#built-in-tokens). Because the anonymous token is used when any request is made to Consul without explicitly specifying a token, production deployments should not apply policies needed for DNS to this token. @@ -583,12 +583,12 @@ DNS lookups and required policies when ACLs are enabled: | Lookup | Type | Description | ACLs Required | | ------------------------------------------------------------------------------ | -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `*.node.consul` | [Node](#node-lookups) | Allow resolving DNS requests for the target node (i.e., `.node.consul`) | [`node:read`](/docs/security/acl/acl-rules#node-rules) | -| `*.service.consul`, `*.connect.consul`, `*.ingress.consul`, `*.virtual.consul` | [Service: standard](#service-lookups) | Allow resolving DNS requests for target service (e.g., `.service.consul`) instances running on ACL-authorized nodes | [`service:read`](/docs/security/acl/acl-rules#service-rules), [`node:read`](/docs/security/acl/acl-rules#node-rules) | -| `*.query.consul` | [Service: prepared query](#prepared-query-lookups) | Allow resolving DNS requests for [service instances specified](/api-docs/query#service-1) by the target prepared query (i.e., `.query.consul`) running on ACL-authorized nodes | [`query:read`](/docs/security/acl/acl-rules#prepared-query-rules), [`service:read`](/docs/security/acl/acl-rules#service-rules), [`node:read`](/docs/security/acl/acl-rules#node-rules) | +| `*.node.consul` | [Node](#node-lookups) | Allow resolving DNS requests for the target node (i.e., `.node.consul`) | [`node:read`](/consul/docs/security/acl/acl-rules#node-rules) | +| `*.service.consul`, `*.connect.consul`, `*.ingress.consul`, `*.virtual.consul` | [Service: standard](#service-lookups) | Allow resolving DNS requests for target service (e.g., `.service.consul`) instances running on ACL-authorized nodes | [`service:read`](/consul/docs/security/acl/acl-rules#service-rules), [`node:read`](/consul/docs/security/acl/acl-rules#node-rules) | +| `*.query.consul` | [Service: prepared query](#prepared-query-lookups) | Allow resolving DNS requests for [service instances specified](/consul/api-docs/query#service-1) by the target prepared query (i.e., `.query.consul`) running on ACL-authorized nodes | [`query:read`](/consul/docs/security/acl/acl-rules#prepared-query-rules), [`service:read`](/consul/docs/security/acl/acl-rules#service-rules), [`node:read`](/consul/docs/security/acl/acl-rules#node-rules) | For guidance on how to configure an appropriate token for DNS, refer to the securing Consul with ACLs guides for: -- [Production Environments](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production#token-for-dns) -- [Development Environments](https://learn.hashicorp.com/tutorials/consul/access-control-setup?utm_source=docs#enable-acls-on-consul-clients) +- [Production Environments](/consul/tutorials/security/access-control-setup-production#token-for-dns) +- [Development Environments](/consul/tutorials/day-0/access-control-setup?utm_source=docs#enable-acls-on-consul-clients) diff --git a/website/content/docs/discovery/services.mdx b/website/content/docs/discovery/services.mdx index 959583fd6a..9eba2e85bb 100644 --- a/website/content/docs/discovery/services.mdx +++ b/website/content/docs/discovery/services.mdx @@ -23,9 +23,9 @@ either specify the configuration file using the `-config-file` option, or specif the directory containing the service definition file with the `-config-dir` option. Consul can load service definitions saved as `.json` or `.hcl` files. -Send a `SIGHUP` to the running agent or use [`consul reload`](/commands/reload) to check for new service definitions or to -update existing services. Alternatively, the service can be [registered dynamically](/api-docs/agent/service#register-service) -using the [HTTP API](/api-docs). +Send a `SIGHUP` to the running agent or use [`consul reload`](/consul/commands/reload) to check for new service definitions or to +update existing services. Alternatively, the service can be [registered dynamically](/consul/api-docs/agent/service#register-service) +using the [HTTP API](/consul/api-docs). A service definition contains a set of parameters that specify various aspects of the service, including how it is discovered by other services in the network. All possible parameters are included in the following example, but only the top-level `service` parameter and its `name` parameter child are required by default. @@ -207,7 +207,7 @@ This is the root-level parameter that defines the service. You can specify the p | `tagged_addresses` | Tagged addresses are additional addresses that may be defined for a node or service. See [Tagged Addresses](#tagged-addresses) for details. | None | Optional | | `port` | Integer value that specifies a service-specific port number. The port number should be specified when the `address` parameter is defined to improve service discoverability. | Optional | | `socket_path` | String value that specifies the path to the service socket.
    Specify this parameter to expose the service to the mesh if the service listens on a Unix Domain socket. | None | Optional | -| `enable_tag_override` | Boolean value that determines if the anti-entropy feature for the service is enabled.
    If set to `true`, then external agents can update this service in the catalog and modify the tags.
    Subsequent local sync operations by this agent will ignore the updated tags.
    This parameter only applies to the locally-registered service. If multiple nodes register the same service, the `enable_tag_override` configuration, and all other service configuration items, operate independently.
    Updating the tags for services registered on one node is independent from the same service (by name) registered on another node.
    See [anti-entropy syncs](/docs/architecture/anti-entropy) for additional information.
    | False | Optional | +| `enable_tag_override` | Boolean value that determines if the anti-entropy feature for the service is enabled.
    If set to `true`, then external agents can update this service in the catalog and modify the tags.
    Subsequent local sync operations by this agent will ignore the updated tags.
    This parameter only applies to the locally-registered service. If multiple nodes register the same service, the `enable_tag_override` configuration, and all other service configuration items, operate independently.
    Updating the tags for services registered on one node is independent from the same service (by name) registered on another node.
    See [anti-entropy syncs](/consul/docs/architecture/anti-entropy) for additional information.
    | False | Optional | | `checks` | Array of objects that define health checks for the service. See [Health Checks](#health-checks) for details. | None | Optional | | `kind` | String value that identifies the service as a Connect proxy. See [Connect](#connect) for details. | None | Optional | | `proxy_destination` | String value that specifies the _name_ of the destination service that the service currently being configured proxies to.
    This parameter is deprecated. Use `proxy.destination_service` instead.
    See [Connect](#connect) for additional information. | None | Optional | @@ -228,9 +228,9 @@ You can add semantic meta data to the service using the `meta` parameter. This p ### Security Configurations If the ACL system is enabled, specify a value for the `token` parameter to provide an ACL token. This token is -used for any interaction with the catalog for the service, including [anti-entropy syncs](/docs/architecture/anti-entropy) and deregistration. +used for any interaction with the catalog for the service, including [anti-entropy syncs](/consul/docs/architecture/anti-entropy) and deregistration. -Services registered in Consul clusters where both [Consul Namespaces](/docs/enterprise/namespaces) +Services registered in Consul clusters where both [Consul Namespaces](/consul/docs/enterprise/namespaces) and the ACL system are enabled can be registered to specific namespaces that are associated with ACL tokens scoped to the namespace. Services registered with a service definition will not inherit the namespace associated with the ACL token specified in the `token` @@ -247,13 +247,13 @@ The health check name is automatically generated as `service:`. If t registered, the ID will be generated as `service::` where `` is an incrementing number starting from `1`. -Consul includes several check types with different options. Refer to the [health checks documentation](/docs/discovery/checks) for details. +Consul includes several check types with different options. Refer to the [health checks documentation](/consul/docs/discovery/checks) for details. ### Proxy Service definitions allow for an optional proxy registration. Proxies used with Connect are registered as services in Consul's catalog. -See the [Proxy Service Registration](/docs/connect/registration/service-registration) reference +See the [Proxy Service Registration](/consul/docs/connect/registration/service-registration) reference for the available configuration options. ### Connect @@ -263,25 +263,25 @@ The `kind` parameter determines the service's role. Services can be configured t The following roles are supported for service entries: - `connect-proxy`: Defines the configuration for a connect proxy -- `ingress-gateway`: Defines the configuration for an [ingress gateway](/docs/connect/config-entries/ingress-gateway) -- `mesh-gateway`: Defines the configuration for a [mesh gateway](/docs/connect/gateways/mesh-gateway) -- `terminating-gateway`: Defines the configuration for a [terminating gateway](/docs/connect/config-entries/terminating-gateway#terminating-gateway) +- `ingress-gateway`: Defines the configuration for an [ingress gateway](/consul/docs/connect/config-entries/ingress-gateway) +- `mesh-gateway`: Defines the configuration for a [mesh gateway](/consul/docs/connect/gateways/mesh-gateway) +- `terminating-gateway`: Defines the configuration for a [terminating gateway](/consul/docs/connect/config-entries/terminating-gateway#terminating-gateway) In the service definition example described above, the service is registered as a proxy because the `kind` property is set to `connect-proxy`. The `proxy` parameter is also required for Connect proxy registrations and is only valid if `kind` is `connect-proxy`. -Refer to the [Proxy Service Registration](/docs/connect/registration/service-registration) documentation for details about this type. +Refer to the [Proxy Service Registration](/consul/docs/connect/registration/service-registration) documentation for details about this type. When the `kind` parameter is set to `connect-proxy`, the only required parameter for the `proxy` configuration is `destination_service_name`. -Refer to the [complete proxy configuration example](/docs/connect/registration/service-registration#complete-configuration-example) for additional information. +Refer to the [complete proxy configuration example](/consul/docs/connect/registration/service-registration#complete-configuration-example) for additional information. -The `connect` field can be specified to configure [Connect](/docs/connect) for a service. This field is available in Consul 1.2.0 and later. The following parameters are available. +The `connect` field can be specified to configure [Connect](/consul/docs/connect) for a service. This field is available in Consul 1.2.0 and later. The following parameters are available. | Parameter | Description | Default | Required | | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- | -------- | -| `native` | Boolean value that advertises the service as [Connect-native](/docs/connect/native).
    If set to `true`, do not configure a `sidecar_service`. | `false` | Optional | -| `sidecar_service` | Object that defines a nested service definition.
    Do not configure if `native` is set to `true`. | See [Sidecar Service Registration](/docs/connect/registration/sidecar-service) for default configurations. | Optional | +| `native` | Boolean value that advertises the service as [Connect-native](/consul/docs/connect/native).
    If set to `true`, do not configure a `sidecar_service`. | `false` | Optional | +| `sidecar_service` | Object that defines a nested service definition.
    Do not configure if `native` is set to `true`. | See [Sidecar Service Registration](/consul/docs/connect/registration/sidecar-service) for default configurations. | Optional | --> **Non-service registration roles**: The `kind` values supported for configuration entries are different than what is supported for service registrations. Refer to the [Configuration Entries](/docs/connect/config-entries) documentation for information about non-service registration types. +-> **Non-service registration roles**: The `kind` values supported for configuration entries are different than what is supported for service registrations. Refer to the [Configuration Entries](/consul/docs/connect/config-entries) documentation for information about non-service registration types. #### Deprecated parameters @@ -290,7 +290,7 @@ Different Consul Connect parameters are supported for different Consul versions. | Parameter | Description | Consul version | Status | | ------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------- | --------------------------------------------------------------------------- | | `proxy_destination` | Specified the proxy destination **in the root level** of the definition file. | 1.2.0 to 1.3.0 | Deprecated since 1.5.0.
    Use `proxy.destination_service_name` instead. | -| `connect.proxy` | Specified "managed" proxies, [which have been deprecated](/docs/connect/proxies/managed-deprecated). | 1.2.0 (beta) to 1.3.0 (beta) | Deprecated. | +| `connect.proxy` | Specified "managed" proxies, [which have been deprecated](/consul/docs/connect/proxies/managed-deprecated). | 1.2.0 (beta) to 1.3.0 (beta) | Deprecated. | ### DNS SRV Weights @@ -314,7 +314,7 @@ is present in the agent DNS configuration or the `passing` query parameter is us Services may also contain a `token` field to provide an ACL token. This token is used for any interaction with the catalog for the service, including -[anti-entropy syncs](/docs/architecture/anti-entropy) and deregistration. +[anti-entropy syncs](/consul/docs/architecture/anti-entropy) and deregistration. You can optionally disable the anti-entropy feature for this service using the `enable_tag_override` flag. External agents can modify tags on services in the @@ -331,7 +331,7 @@ configuration items are independent of one another. Updating the tags for the service registered on one node is independent of the same service (by name) registered on another node. If `enable_tag_override` is not specified the default value is false. See [anti-entropy -syncs](/docs/architecture/anti-entropy) for more info. +syncs](/consul/docs/architecture/anti-entropy) for more info. For Consul 0.9.3 and earlier you need to use `enableTagOverride`. Consul 1.0 supports both `enable_tag_override` and `enableTagOverride` but the latter is @@ -383,7 +383,7 @@ The following table provides an overview of the various tagged address types sup | Type | Description | Tags | | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------- | | LAN | LAN addresses are intended to be directly accessible only from services within the same Consul data center. See [LAN tags](#lan-tags) for details. | `lan`
    `lan_ipv4`
    `lan_ipv6` | -| Virtual | Virtual tagged addresses are logical address types that can be configured on [Connect](/docs/connect)-enabled services. The virtual address provides a fixed IP address that can be used by downstream services when connecting to an upstream service. See [Virtual tags](#virtual-tags) for details. | `virtual` | +| Virtual | Virtual tagged addresses are logical address types that can be configured on [Connect](/consul/docs/connect)-enabled services. The virtual address provides a fixed IP address that can be used by downstream services when connecting to an upstream service. See [Virtual tags](#virtual-tags) for details. | `virtual` | | WAN | Define a WAN address for the service or node when it should be accessed at an alternate address by services in a remote datacenter. See [WAN tags](#wan-tags) for details. | `wan`
    `wan_ipv4`
    `wan_ipv6` | #### LAN tags @@ -453,10 +453,10 @@ service { Connections to virtual addresses are load balanced across available instances of a service, provided the following conditions are satisfied: -1. [Transparent proxy](/docs/connect/transparent-proxy) is enabled for the +1. [Transparent proxy](/consul/docs/connect/transparent-proxy) is enabled for the downstream and upstream services. 1. The upstream service is not configured for individual instances to be - [dialed directly](/docs/connect/config-entries/service-defaults#dialeddirectly). + [dialed directly](/consul/docs/connect/config-entries/service-defaults#dialeddirectly). Virtual addresses are not required to be routable IPs within the network. They are strictly a control plane construct used to provide a fixed @@ -676,7 +676,7 @@ services { ## Service and Tag Names with DNS -Consul exposes service definitions and tags over the [DNS](/docs/discovery/dns) +Consul exposes service definitions and tags over the [DNS](/consul/docs/discovery/dns) interface. DNS queries have a strict set of allowed characters and a well-defined format that Consul cannot override. While it is possible to register services or tags with names that don't match the conventions, those diff --git a/website/content/docs/dynamic-app-config/kv.mdx b/website/content/docs/dynamic-app-config/kv.mdx index 00a1193ef9..36656c3ae3 100644 --- a/website/content/docs/dynamic-app-config/kv.mdx +++ b/website/content/docs/dynamic-app-config/kv.mdx @@ -16,31 +16,31 @@ similarities to one. The Consul KV datastore is located on the servers, but can be accessed by any agent (client or server). The natively integrated [RPC -functionality](/docs/architecture) allows clients to forward +functionality](/consul/docs/architecture) allows clients to forward requests to servers, including key/value reads and writes. Part of Consul's core design allows data to be replicated automatically across all the servers. Having a quorum of servers will decrease the risk of data loss if an outage occurs. If you have not used Consul KV, complete this [Getting Started -tutorial](https://learn.hashicorp.com/tutorials/consul/get-started-key-value-store?utm_source=docs) on HashiCorp. +tutorial](/consul/tutorials/interactive/get-started-key-value-store?utm_source=docs) on HashiCorp. ## Accessing the KV store The KV store can be accessed by the [consul kv CLI -subcommands](/commands/kv), [HTTP API](/api-docs/kv), and Consul UI. +subcommands](/consul/commands/kv), [HTTP API](/consul/api-docs/kv), and Consul UI. To restrict access, enable and configure -[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production). +[ACLs](/consul/tutorials/security/access-control-setup-production). Once the ACL system has been bootstrapped, users and services, will need a -valid token with KV [privileges](/docs/security/acl/acl-rules#key-value-rules) to +valid token with KV [privileges](/consul/docs/security/acl/acl-rules#key-value-rules) to access the the data store, this includes even reads. We recommend creating a token with limited privileges, for example, you could create a token with write privileges on one key for developers to update the value related to their application. The datastore itself is located on the Consul servers in the [data -directory](/docs/agent/config/cli-flags#_data_dir). To ensure data is not lost in -the event of a complete outage, use the [`consul snapshot`](/commands/snapshot/restore) feature to backup the data. +directory](/consul/docs/agent/config/cli-flags#_data_dir). To ensure data is not lost in +the event of a complete outage, use the [`consul snapshot`](/consul/commands/snapshot/restore) feature to backup the data. ## Using Consul KV @@ -48,7 +48,7 @@ Objects are opaque to Consul, meaning there are no restrictions on the type of object stored in a key/value entry. The main restriction on an object is size - the maximum is 512 KB. Due to the maximum object size and main use cases, you should not need extra storage; the general [sizing -recommendations](/docs/agent/config/config-files#kv_max_value_size) +recommendations](/consul/docs/agent/config/config-files#kv_max_value_size) are usually sufficient. Keys, like objects are not restricted by type and can include any character. @@ -67,7 +67,7 @@ using the API and in shell scripts. If you plan to use Consul KV as part of your configuration management process review the [Consul -Template](https://learn.hashicorp.com/tutorials/consul/consul-template?utm_source=docs) +Template](/consul/tutorials/developer-configuration/consul-template?utm_source=docs) tutorial on how to update configuration based on value updates in the KV. Consul Template is based on Go Templates and allows for a series of scripted actions to be initiated on value changes to a Consul key. @@ -75,9 +75,9 @@ to be initiated on value changes to a Consul key. ### Watches Consul KV can also be extended with the use of watches. -[Watches](/docs/dynamic-app-config/watches) are a way to monitor data for updates. When +[Watches](/consul/docs/dynamic-app-config/watches) are a way to monitor data for updates. When an update is detected, an external handler is invoked. To use watches with the -KV store the [key](/docs/dynamic-app-config/watches#key) watch type should be used. +KV store the [key](/consul/docs/dynamic-app-config/watches#key) watch type should be used. ### Consul Sessions @@ -87,9 +87,9 @@ API supports an `acquire` and `release` operation. The `acquire` operation acts like a Check-And-Set operation. On success, there is a key update and an increment to the `LockIndex` and the session value is updated to reflect the session holding the lock. Review the session documentation for more information -on the [integration](/docs/dynamic-app-config/sessions#k-v-integration). +on the [integration](/consul/docs/dynamic-app-config/sessions#k-v-integration). -Review the following tutorials to learn how to use Consul sessions for [application leader election](https://learn.hashicorp.com/tutorials/consul/application-leader-elections) and +Review the following tutorials to learn how to use Consul sessions for [application leader election](/consul/tutorials/developer-configuration/application-leader-elections) and to [build distributed semaphores](https://learn.hashicorp.com/consul/developer-configuration/semaphore). ### Vault diff --git a/website/content/docs/dynamic-app-config/sessions.mdx b/website/content/docs/dynamic-app-config/sessions.mdx index 729c1b312b..eb0c4cf495 100644 --- a/website/content/docs/dynamic-app-config/sessions.mdx +++ b/website/content/docs/dynamic-app-config/sessions.mdx @@ -48,7 +48,7 @@ deleted by Consul. While this is a simple design, it enables a multitude of usage patterns. By default, the -[gossip based failure detector](/docs/architecture/gossip) +[gossip based failure detector](/consul/docs/architecture/gossip) is used as the associated health check. This failure detector allows Consul to detect when a node that is holding a lock has failed and to automatically release the lock. This ability provides **liveness** to @@ -136,7 +136,7 @@ the goal of Consul to protect against misbehaving clients. The primitives provided by sessions and the locking mechanisms of the KV store can be used to build client-side leader election algorithms. -These are covered in more detail in the [Leader Election guide](https://learn.hashicorp.com/tutorials/consul/application-leader-elections). +These are covered in more detail in the [Leader Election guide](/consul/tutorials/developer-configuration/application-leader-elections). ## Prepared Query Integration diff --git a/website/content/docs/dynamic-app-config/watches.mdx b/website/content/docs/dynamic-app-config/watches.mdx index 54f7e96e78..cb6ef64480 100644 --- a/website/content/docs/dynamic-app-config/watches.mdx +++ b/website/content/docs/dynamic-app-config/watches.mdx @@ -12,15 +12,15 @@ checks) which is monitored for updates. When an update is detected, an external is invoked. A handler can be any executable or HTTP endpoint. As an example, you could watch the status of health checks and notify an external system when a check is critical. -Watches are implemented using blocking queries in the [HTTP API](/api-docs). +Watches are implemented using blocking queries in the [HTTP API](/consul/api-docs). Agents automatically make the proper API calls to watch for changes and inform a handler when the data view has updated. -Watches can be configured as part of the [agent's configuration](/docs/agent/config/config-files#watches), +Watches can be configured as part of the [agent's configuration](/consul/docs/agent/config/config-files#watches), causing them to run once the agent is initialized. Reloading the agent configuration allows for adding or removing watches dynamically. -Alternatively, the [watch command](/commands/watch) enables a watch to be +Alternatively, the [watch command](/consul/commands/watch) enables a watch to be started outside of the agent. This can be used by an operator to inspect data in Consul or to easily pipe data into processes without being tied to the agent lifecycle. @@ -37,7 +37,7 @@ with invocation info, following a format that depends on the type of the watch. Each watch type documents the format type. Because they map directly to an HTTP API, handlers should expect the input to match the format of the API. A Consul index is also given, corresponding to the responses from the -[HTTP API](/api-docs). +[HTTP API](/consul/api-docs). ### Executable @@ -634,7 +634,7 @@ An example of the output of this command: ### Type: event ((#event)) The "event" watch type is used to monitor for custom user -events. These are fired using the [consul event](/commands/event) command. +events. These are fired using the [consul event](/consul/commands/event) command. It takes only a single optional `name` parameter which restricts the watch to only events with the given name. diff --git a/website/content/docs/ecs/architecture.mdx b/website/content/docs/ecs/architecture.mdx index 73216277f6..a0c84805a6 100644 --- a/website/content/docs/ecs/architecture.mdx +++ b/website/content/docs/ecs/architecture.mdx @@ -24,11 +24,11 @@ The following diagram shows the main components of the Consul architecture when 1. **Health Syncing:** Optionally, an additional `health-sync` container can be included in a task to sync health statuses from ECS into Consul. 1. **ACL Controller:** The ACL controller is responsible for automating configuration and cleanup in the Consul servers. - The ACL controller will automatically configure the [AWS IAM Auth Method](/docs/security/acl/auth-methods/aws-iam), and cleanup + The ACL controller will automatically configure the [AWS IAM Auth Method](/consul/docs/security/acl/auth-methods/aws-iam), and cleanup unused ACL tokens from Consul. When using Consul Enterprise namespaces, the ACL controller will automatically create Consul namespaces for ECS tasks. -For more information about how Consul works in general, see Consul's [Architecture Overview](/docs/architecture). +For more information about how Consul works in general, see Consul's [Architecture Overview](/consul/docs/architecture). ## Task Startup @@ -113,12 +113,12 @@ names on ECS are not known until runtime. ### Service Token -Service tokens are associated with a [service identity](/docs/security/acl#service-identities). +Service tokens are associated with a [service identity](/consul/docs/security/acl#service-identities). The service identity includes `service:write` permissions for the service and sidecar proxy. ## AWS IAM Auth Method -Consul's [AWS IAM Auth Method](/docs/security/acl/auth-methods/aws-iam) is used by ECS tasks to +Consul's [AWS IAM Auth Method](/consul/docs/security/acl/auth-methods/aws-iam) is used by ECS tasks to automatically obtain Consul ACL tokens. When a service mesh task on ECS starts up, it runs two `consul login` commands to obtain a client token and a service token via the auth method. When the task stops, it attempts two `consul logout` commands in order to destroy these tokens. @@ -127,7 +127,7 @@ During a `consul login`, the [task's IAM role](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task-iam-roles.html) is presented to the AWS IAM auth method on the Consul servers. The role is validated with AWS. If the role is valid, and if the auth method trusts the IAM role, then the role is permitted to login. A new Consul -ACL token is created and [Binding Rules](/docs/security/acl/auth-methods#binding-rules) associate +ACL token is created and [Binding Rules](/consul/docs/security/acl/auth-methods#binding-rules) associate permissions with the newly created token. These permissions are mapped to the token based on the IAM role details. For example, tags on the IAM role are used to specify the service name and the Consul Enterprise namespace to be associated with a service token that is created by a successful @@ -195,7 +195,7 @@ are created by the ACL controller when it starts up: token created during a successful login to this auth method instance. * **Auth method for service tokens**: One instance of the AWS IAM auth method is created for service tokens, if it does not exist: - * A binding rule is configured to attach a [service identity](/docs/security/acl#service-identities) + * A binding rule is configured to attach a [service identity](/consul/docs/security/acl#service-identities) to each token created during a successful login to this auth method instance. The service name for this service identity is taken from the tag, `consul.hashicorp.com.service-name`, on the IAM role used to log in. @@ -204,7 +204,7 @@ are created by the ACL controller when it starts up: role used to log in. The ACL controller configures both instances of the auth method to permit only certain IAM roles to login, -by setting the [`BoundIAMPrincipalARNs`](/docs/security/acl/auth-methods/aws-iam#boundiamprincipalarns) +by setting the [`BoundIAMPrincipalARNs`](/consul/docs/security/acl/auth-methods/aws-iam#boundiamprincipalarns) field of the AWS IAM auth method as follows: * By default, the only IAM roles permitted to log in must have an ARN matching the pattern, @@ -231,7 +231,7 @@ The ACL controller runs continually to ensure those unused tokens are soon remov ### Admin Partitions and Namespaces -When [admin partitions and namespaces](/docs/ecs/enterprise#admin-partitions-and-namespaces) are enabled, +When [admin partitions and namespaces](/consul/docs/ecs/enterprise#admin-partitions-and-namespaces) are enabled, the ACL controller is assigned to its configured admin partition. It supports one ACL controller instance per ECS cluster. This results in an architecture with one admin partition per ECS cluster. diff --git a/website/content/docs/ecs/compatibility.mdx b/website/content/docs/ecs/compatibility.mdx index 2b6716cdb8..803d4e3c26 100644 --- a/website/content/docs/ecs/compatibility.mdx +++ b/website/content/docs/ecs/compatibility.mdx @@ -22,4 +22,4 @@ For every release of Consul on ECS, the `consul-ecs` binary and `consul-ecs` Ter ## Supported Envoy versions -Refer to [Envoy - Supported Versions](/docs/connect/proxies/envoy#supported-versions) for information about which versions of Envoy are supported for each version of Consul. As a best practice, we recommend using the default version of Envoy that is provided in the Terraform module. This is because we test the default versions with Consul ECS binaries for the given version. +Refer to [Envoy - Supported Versions](/consul/docs/connect/proxies/envoy#supported-versions) for information about which versions of Envoy are supported for each version of Consul. As a best practice, we recommend using the default version of Envoy that is provided in the Terraform module. This is because we test the default versions with Consul ECS binaries for the given version. diff --git a/website/content/docs/ecs/configuration-reference.mdx b/website/content/docs/ecs/configuration-reference.mdx index 4264fb8f9e..da0ee28f68 100644 --- a/website/content/docs/ecs/configuration-reference.mdx +++ b/website/content/docs/ecs/configuration-reference.mdx @@ -185,7 +185,7 @@ Defines the Consul checks for the service. Each `check` object may contain the f | `method` | `string` | optional | Specifies the HTTP method to be used for an HTTP check. When no value is specified, `GET` is used. | | `name` | `string` | optional | The name of the check. | | `notes` | `string` | optional | Specifies arbitrary information for humans. This is not used by Consul internally. | -| `os_service` | `string` | optional | Specifies the name of a service on which to perform an [OS service check](/docs/discovery/checks#osservice-check). The check runs according the frequency specified in the `interval` parameter. | +| `os_service` | `string` | optional | Specifies the name of a service on which to perform an [OS service check](/consul/docs/discovery/checks#osservice-check). The check runs according the frequency specified in the `interval` parameter. | | `status` | `string` | optional | Specifies the initial status the health check. Must be one of `passing`, `warning`, `critical`, `maintenance`, or `null`. | | `successBeforePassing` | `integer` | optional | Specifies the number of consecutive successful results required before check status transitions to passing. | | `tcp` | `string` | optional | Specifies this is a TCP check. Must be an IP/hostname plus port to which a TCP connection is made every `interval`. | diff --git a/website/content/docs/ecs/enterprise.mdx b/website/content/docs/ecs/enterprise.mdx index fe7c1750f4..1063453455 100644 --- a/website/content/docs/ecs/enterprise.mdx +++ b/website/content/docs/ecs/enterprise.mdx @@ -26,9 +26,9 @@ module "my_task" { ## Licensing -!> **Warning:** Consul Enterprise is currently only fully supported when [ACLs are enabled](/docs/ecs/terraform/secure-configuration). +!> **Warning:** Consul Enterprise is currently only fully supported when [ACLs are enabled](/consul/docs/ecs/terraform/secure-configuration). -Consul Enterprise [requires a license](/docs/enterprise/license/overview). If running +Consul Enterprise [requires a license](/consul/docs/enterprise/license/overview). If running Consul on ECS with ACLs enabled, the license will be automatically pulled down from Consul servers. Currently there is no capability for specifying the license when ACLs are disabled so if you wish to @@ -60,7 +60,7 @@ If client support is required for any of the features, then you must use a Consu ### Admin Partitions and Namespaces -Consul on ECS supports [admin partitions](/docs/enterprise/admin-partitions) and [namespaces](/docs/enterprise/namespaces) when Consul Enterprise servers and clients are used. These features have the following requirements: +Consul on ECS supports [admin partitions](/consul/docs/enterprise/admin-partitions) and [namespaces](/consul/docs/enterprise/namespaces) when Consul Enterprise servers and clients are used. These features have the following requirements: - ACLs must be enabled. - ACL controller must run in the ECS cluster. @@ -95,7 +95,7 @@ module "acl_controller" {     -Services are assigned to admin partitions and namespaces through the use of [task tags](/docs/ecs/manual/install#task-tags). +Services are assigned to admin partitions and namespaces through the use of [task tags](/consul/docs/ecs/manual/install#task-tags). The `mesh-task` module automatically adds the necessary tags to the task definition. If the ACL controller is configured for admin partitions, services on the mesh will always be assigned to an admin partition and namespace. If the `mesh-task` does not define @@ -124,7 +124,7 @@ module "my_task" { ### Audit Logging -Consul on ECS supports [audit logging](/docs/enterprise/audit-logging) when using Consul Enterprise clients. +Consul on ECS supports [audit logging](/consul/docs/enterprise/audit-logging) when using Consul Enterprise clients. This feature has the following requirements: - ACLs must be enabled. diff --git a/website/content/docs/ecs/index.mdx b/website/content/docs/ecs/index.mdx index 8dc22fccca..20c7b27296 100644 --- a/website/content/docs/ecs/index.mdx +++ b/website/content/docs/ecs/index.mdx @@ -7,7 +7,7 @@ description: >- # Consul on AWS Elastic Container Service (ECS) Overview -You can deploy Consul service mesh applications to [AWS Elastic Container Service](https://aws.amazon.com/ecs/) (ECS) using either our official [Terraform modules](/docs/ecs/terraform/install) or by [manually configuring the task definition](/docs/ecs/manual/install). +You can deploy Consul service mesh applications to [AWS Elastic Container Service](https://aws.amazon.com/ecs/) (ECS) using either our official [Terraform modules](/consul/docs/ecs/terraform/install) or by [manually configuring the task definition](/consul/docs/ecs/manual/install). ## Service Mesh @@ -19,23 +19,23 @@ traffic policy, and more. You can also connect service meshes so that services d ![Consul on ECS Architecture](/img/consul-ecs-arch.png) -Consul on ECS follows an [architecture](/docs/architecture) similar to other platforms, but each ECS task is a +Consul on ECS follows an [architecture](/consul/docs/architecture) similar to other platforms, but each ECS task is a Consul node. An ECS task runs the user application container(s), as well as a Consul client container for control plane communication and an [Envoy](https://envoyproxy.io/) sidecar proxy container to facilitate data plane communication for -[Consul Connect](/docs/connect). +[Consul Connect](/consul/docs/connect). -For a detailed architecture overview, see the [Architecture](/docs/ecs/architecture) page. +For a detailed architecture overview, see the [Architecture](/consul/docs/ecs/architecture) page. ## Getting Started There are several ways to get started with Consul with ECS. -- The [Serverless Consul Service Mesh with ECS and HCP](https://learn.hashicorp.com/tutorials/cloud/consul-ecs-hcp?utm_source=docs) learn guide shows how to use Terraform to run Consul service mesh applications on ECS with managed Consul servers running in HashiCorp Cloud Platform (HCP). -- The [Service Mesh with ECS and Consul on EC2](https://learn.hashicorp.com/tutorials/consul/consul-ecs-ec2?utm_source=docs) learn guide shows how to use Terraform to run Consul service mesh applications on ECS with Consul servers running on EC2 instances. +- The [Serverless Consul Service Mesh with ECS and HCP](/consul/tutorials/cloud-production/consul-ecs-hcp?utm_source=docs) learn guide shows how to use Terraform to run Consul service mesh applications on ECS with managed Consul servers running in HashiCorp Cloud Platform (HCP). +- The [Service Mesh with ECS and Consul on EC2](/consul/tutorials/cloud-integrations/consul-ecs-ec2?utm_source=docs) learn guide shows how to use Terraform to run Consul service mesh applications on ECS with Consul servers running on EC2 instances. - The [Consul with Dev Server on Fargate](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/examples/dev-server-fargate) example installation deploys a sample application in ECS using the Fargate launch type. - The [Consul with Dev Server on EC2](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/examples/dev-server-ec2) example installation deploys a sample application in ECS using the EC2 launch type. -Refer to the [Requirements](/docs/ecs/requirements) and use one of the following sets of instructions when you're ready to install Consul on an existing ECS cluster and add tasks to the service mesh: +Refer to the [Requirements](/consul/docs/ecs/requirements) and use one of the following sets of instructions when you're ready to install Consul on an existing ECS cluster and add tasks to the service mesh: -- [Install with Terraform](/docs/ecs/terraform/install) -- [Install Manually](/docs/ecs/manual/install) +- [Install with Terraform](/consul/docs/ecs/terraform/install) +- [Install Manually](/consul/docs/ecs/manual/install) diff --git a/website/content/docs/ecs/manual/acl-controller.mdx b/website/content/docs/ecs/manual/acl-controller.mdx index 38aff74bd6..bb7d88638a 100644 --- a/website/content/docs/ecs/manual/acl-controller.mdx +++ b/website/content/docs/ecs/manual/acl-controller.mdx @@ -7,13 +7,13 @@ description: >- # Manual Installation of ACL Controller for Consul on AWS Elastic Container Service (ECS) -This topic describes how to manually deploy the ACL controller, which will automatically configure the [AWS IAM Auth Method](/docs/security/acl/auth-methods/aws-iam). If you are using Terraform, refer to the [Terraform Secure Configuration](/docs/ecs/terraform/secure-configuration) page to deploy the ACL controller. +This topic describes how to manually deploy the ACL controller, which will automatically configure the [AWS IAM Auth Method](/consul/docs/security/acl/auth-methods/aws-iam). If you are using Terraform, refer to the [Terraform Secure Configuration](/consul/docs/ecs/terraform/secure-configuration) page to deploy the ACL controller. ## Prerequisites * Your application tasks must include certain tags to be compatible with the ACL controller. -Refer to the [Task Tags](/docs/ecs/manual/install#task-tags) section of the installation page. -* You should be familiar with configuring Consul's secure features, including how to create ACL tokens and policies. Refer to the [Consul Security tutorials](https://learn.hashicorp.com/collections/consul/security) for an introduction and the [ACL system](/docs/security/acl) documentation for more information. +Refer to the [Task Tags](/consul/docs/ecs/manual/install#task-tags) section of the installation page. +* You should be familiar with configuring Consul's secure features, including how to create ACL tokens and policies. Refer to the [Consul Security tutorials](/consul/tutorials/security) for an introduction and the [ACL system](/consul/docs/security/acl) documentation for more information. * If you are using Consul with multiple ECS clusters, each cluster requires its own instance of the ACL controller. ## Set Up Secrets @@ -121,7 +121,7 @@ to complete the remaining details for your use case. | `desiredCount` | integer | Must be `1`. Only one instance of the ACL controller should run per ECS cluster. | | `launchType` | string | Consul on ECS supports both the `FARGATE` and `EC2` launch types. | | `serviceName` | string | The service name of your choice. | -| `taskDefinition` | string | Must be set to the ACL controller [task definition](/docs/ecs/manual/acl-controller#task-definition). | +| `taskDefinition` | string | Must be set to the ACL controller [task definition](/consul/docs/ecs/manual/acl-controller#task-definition). | ## AWS IAM Roles diff --git a/website/content/docs/ecs/manual/install.mdx b/website/content/docs/ecs/manual/install.mdx index ffc4111fa2..e648c6cf3e 100644 --- a/website/content/docs/ecs/manual/install.mdx +++ b/website/content/docs/ecs/manual/install.mdx @@ -7,11 +7,11 @@ description: >- # Manual Installation of Consul on AWS Elastic Container Service (ECS) -The following instructions describe how to use the [`consul-ecs` Docker image](https://gallery.ecr.aws/hashicorp/consul-ecs) to manually create the ECS task definition without Terraform. If you prefer to use Terraform, refer to [Consul ECS Terraform module](/docs/ecs/terraform/install). +The following instructions describe how to use the [`consul-ecs` Docker image](https://gallery.ecr.aws/hashicorp/consul-ecs) to manually create the ECS task definition without Terraform. If you prefer to use Terraform, refer to [Consul ECS Terraform module](/consul/docs/ecs/terraform/install). If you intend to peer the service mesh to multiple Consul datacenters or partitions, you must use the Consul ECS Terraform module to install your service mesh on ECS. Manually configuring mesh gateways without using the `gateway-task` Terraform module is not supported. -This topic does not include instructions for creating all AWS resources necessary to install Consul, such as a VPC or the ECS cluster. Refer to the linked guides in the [Getting Started](/docs/ecs#getting-started) section for complete, runnable examples. +This topic does not include instructions for creating all AWS resources necessary to install Consul, such as a VPC or the ECS cluster. Refer to the linked guides in the [Getting Started](/consul/docs/ecs#getting-started) section for complete, runnable examples. ## Prerequisites @@ -71,7 +71,7 @@ during task startup. ### Task Tags -The `tags` list must include the following if you are using the ACL controller in a [secure configuration](/docs/ecs/manual/secure-configuration). +The `tags` list must include the following if you are using the ACL controller in a [secure configuration](/consul/docs/ecs/manual/secure-configuration). Without these tags, the ACL controller will be unable to provision a service token for the task. | Tag Key | Tag Value | Description | @@ -88,7 +88,7 @@ in the task definition. Ensure that the `containerName` and `condition` fields in the `dependsOn` list are specified as described in the following example. These are container dependencies, -which must be used to enforce a specific [startup order](/docs/ecs/architecture#task-startup). +which must be used to enforce a specific [startup order](/consul/docs/ecs/architecture#task-startup). By using the following settings, your application container will start after `consul-ecs-mesh-init` has completed task setup and after `sidecar-proxy` is ready to proxy traffic between this task and the service mesh. @@ -127,7 +127,7 @@ See the [ECS Task Definition](https://docs.aws.amazon.com/AmazonECS/latest/devel ## `sidecar-proxy` container -The `sidecar-proxy` container runs [Envoy proxy](/docs/connect/proxies/envoy) for Consul Connect. In most cases, the container should contain the following parameters and values. +The `sidecar-proxy` container runs [Envoy proxy](/consul/docs/connect/proxies/envoy) for Consul Connect. In most cases, the container should contain the following parameters and values. The `mountPoints` list must be set as shown in the following example. This will mount the shared `consul_data` volume into the `sidecar-proxy` container at the path `/consul`. This volume is where the `consul-ecs-mesh-init` container copies the `envoy-bootstrap.json` @@ -188,7 +188,7 @@ The following table describes the necessary configuration settings. | Field name | Type | Description | | ------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `name` | string | The container name, which must be `sidecar-proxy`. | -| `image` | string | The Envoy image. This must be a [supported version of Envoy](/docs/connect/proxies/envoy#supported-versions). | +| `image` | string | The Envoy image. This must be a [supported version of Envoy](/consul/docs/connect/proxies/envoy#supported-versions). | | `dependsOn` | list | Must be set as shown above to ensure Envoy starts after the `consul-ecs-mesh-init` container has written the `envoy-bootstrap.json` config file for Envoy. | | `healthCheck` | list | Must be set as shown above to monitor the health of Envoy's primary listener port, which ties into container dependencies and startup ordering. | | `mountPoints` | list | Must be set as shown above to access the files shared in the `/consul` directory, like the Envoy bootstrap configuration file and the `consul-ecs` binary. | @@ -196,7 +196,7 @@ The following table describes the necessary configuration settings. | `entrypoint` | list | Must be set to the custom Envoy entrypoint, `consul-ecs envoy-entrypoint`, to facilitate graceful shutdown. | | `command` | list | The startup command. This passes the bootstrap configuration to Envoy. | --> **NOTE**: Envoy and Consul must be compatible versions. See the [supported versions of Envoy](/docs/connect/proxies/envoy#supported-versions) in the Consul documentation. +-> **NOTE**: Envoy and Consul must be compatible versions. See the [supported versions of Envoy](/consul/docs/connect/proxies/envoy#supported-versions) in the Consul documentation. ## `consul-client` container @@ -304,7 +304,7 @@ The following table describes the values that you should use to configure the `c -> **NOTE**: Use `exec` to start the Consul agent so that the Consul agent runs as PID 1. This ensures the Consul agent directly receives signals from ECS, which is important for graceful shutdown of the Consul agent. -Refer to the [Consul Agent documentation](/docs/agent/config/config-files#configuration_files) for a complete reference of Consul agent +Refer to the [Consul Agent documentation](/consul/docs/agent/config/config-files#configuration_files) for a complete reference of Consul agent configuration options. ## `consul-ecs-mesh-init` container @@ -369,7 +369,7 @@ configuration to a shared volume. | `image` | string | The `consul-ecs` image. Use our public AWS registry, `public.ecr.aws/hashicorp/consul-ecs`, to avoid rate limits. | | `mountPoints` | list | Must be set as show above, so the `consul` and `consul-ecs` binaries can be shared among containers for task setup. | | `command` | list | Set to `["mesh-init"]` so that the container runs the `consul-ecs mesh-init` command. | -| `environment` | list | This must include the [`CONSUL_ECS_CONFIG_JSON`](/docs/ecs/manual/install#consul_ecs_config_json) variable. See below for details. | +| `environment` | list | This must include the [`CONSUL_ECS_CONFIG_JSON`](/consul/docs/ecs/manual/install#consul_ecs_config_json) variable. See below for details. | ### `CONSUL_ECS_CONFIG_JSON` @@ -377,7 +377,7 @@ Configuration is passed to the `consul-ecs` binary in JSON format using the `CON The following is an example of the configuration that might be used for a service named `example-client-app` with one upstream service name `example-server-app`. The `proxy` and `service` blocks include information used by `consul-ecs-mesh-init` to perform -[service registration](/docs/discovery/services) with Consul during task startup. The same configuration format is used for +[service registration](/consul/docs/discovery/services) with Consul during task startup. The same configuration format is used for the `consul-ecs-health-sync` container. ```json @@ -405,13 +405,13 @@ the `consul-ecs-health-sync` container. | Field name | Type | Description | | ---------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `bootstrapDir` | string | This is the path of a shared volume that is mounted to other containers, where `consul-ecs-mesh-init` will write out Envoy configuration. | -| `healthSyncContainers` | list | Used for [health status syncing](/docs/ecs/architecture#ecs-health-check-syncing) from ECS to Consul. See below for details. | +| `healthSyncContainers` | list | Used for [health status syncing](/consul/docs/ecs/architecture#ecs-health-check-syncing) from ECS to Consul. See below for details. | | `proxy.upstreams` | list | The upstream services that your application calls over the service mesh, if any. The `destinationName` and `localBindPort` fields are required. | | `service.name` | string | The name used to register this service into the Consul service catalog. | | `service.port` | integer | The port your application listens on. Set to `0` if your application does not listen on any port. | -| `service.checks` | list | Consul [checks](/docs/discovery/checks) to include so that Consul can run health checks against your application. | +| `service.checks` | list | Consul [checks](/consul/docs/discovery/checks) to include so that Consul can run health checks against your application. | -See the [Configuration Reference](/docs/ecs/configuration-reference) for a complete reference of fields. +See the [Configuration Reference](/consul/docs/ecs/configuration-reference) for a complete reference of fields. ## `consul-ecs-health-sync` container @@ -553,4 +553,4 @@ and `consul-ecs-mesh-init` containers. * Create the task definition using the [AWS Console](https://docs.aws.amazon.com/AmazonECS/latest/userguide/create-task-definition-classic.html) or the [AWS CLI](https://docs.aws.amazon.com/cli/latest/reference/ecs/register-task-definition.html), or another method of your choice. * Create an [ECS Service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html) to start tasks using the task definition. -* Follow the [Secure Configuration](/docs/ecs/manual/secure-configuration) to get production-ready. +* Follow the [Secure Configuration](/consul/docs/ecs/manual/secure-configuration) to get production-ready. diff --git a/website/content/docs/ecs/manual/secure-configuration.mdx b/website/content/docs/ecs/manual/secure-configuration.mdx index c6fbf439e4..5a94ed4acd 100644 --- a/website/content/docs/ecs/manual/secure-configuration.mdx +++ b/website/content/docs/ecs/manual/secure-configuration.mdx @@ -13,28 +13,28 @@ This topic describes how to enable Consul security features for your production The following features must be configured for your Consul server cluster: -- [TLS encryption](/docs/security/encryption#rpc-encryption-with-tls) for RPC communication between Consul clients and servers. -- [Gossip encryption](/docs/security/encryption#gossip-encryption) for encrypting gossip traffic. -- [Access control lists (ACLs)](/docs/security/acl) for authentication and authorization for Consul clients and services on the mesh. +- [TLS encryption](/consul/docs/security/encryption#rpc-encryption-with-tls) for RPC communication between Consul clients and servers. +- [Gossip encryption](/consul/docs/security/encryption#gossip-encryption) for encrypting gossip traffic. +- [Access control lists (ACLs)](/consul/docs/security/acl) for authentication and authorization for Consul clients and services on the mesh. -You should already have followed the [manual installation instructions](/docs/ecs/manual/install) to define the necessary components of the task definition for Consul on ECS. +You should already have followed the [manual installation instructions](/consul/docs/ecs/manual/install) to define the necessary components of the task definition for Consul on ECS. You should be familiar with [specifying sensitive data](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/specifying-sensitive-data.html) on ECS. -You should be familiar with configuring Consul's secure features, including how to create ACL tokens and policies. Refer to the [ACL system documentation](/docs/security/acl) and [Day 1: Security tutorials](https://learn.hashicorp.com/collections/consul/security) for an introduction and additional information. +You should be familiar with configuring Consul's secure features, including how to create ACL tokens and policies. Refer to the [ACL system documentation](/consul/docs/security/acl) and [Day 1: Security tutorials](/consul/tutorials/security) for an introduction and additional information. ## Auth Method Tokens are artifacts within the ACL system that authenticate users, services, and Consul agents. Tokens are linked to policies that specify the resources the token bearer has access to when making requests in the network. -Auth Methods are a Consul server component that performs authentication against a trusted external party to authorize the creation of ACL tokens. The [AWS IAM auth method](/docs/security/acl/auth-methods/aws-iam) is used to enable an ECS task to automatically obtain ACL tokens when the task starts up. +Auth Methods are a Consul server component that performs authentication against a trusted external party to authorize the creation of ACL tokens. The [AWS IAM auth method](/consul/docs/security/acl/auth-methods/aws-iam) is used to enable an ECS task to automatically obtain ACL tokens when the task starts up. There are two types of ACL tokens for Consul on ECS: * **Client tokens:** used by the `consul-client` containers to join the Consul cluster * **Service tokens:** used by sidecar containers for service registration and health syncing -This section describes how to manually configure the AWS IAM auth method for Consul on ECS. Alternatively, you can install the ACL controller to ease the burden of creating these resources. The ACL controller can automatically configure ACL resources for Consul on ECS. For additional details, refer to [ACL Controller](/docs/ecs/manual/acl-controller) and [Architecture](/docs/ecs/architecture). +This section describes how to manually configure the AWS IAM auth method for Consul on ECS. Alternatively, you can install the ACL controller to ease the burden of creating these resources. The ACL controller can automatically configure ACL resources for Consul on ECS. For additional details, refer to [ACL Controller](/consul/docs/ecs/manual/acl-controller) and [Architecture](/consul/docs/ecs/architecture). ### ECS Task Role Configuration @@ -49,7 +49,7 @@ The task role must be configured with the following details to compatible with t method. * An `iam:GetRole` permission to fetch itself. See - [IAM Policies](/docs/security/acl/auth-methods/aws-iam#iam-policies) for details. + [IAM Policies](/consul/docs/security/acl/auth-methods/aws-iam#iam-policies) for details. * A `consul.hashicorp.com.service-name` tag on the task role which contains the Consul service name for the application in this task. * A consul.hashicorp.com.namespace tag on the task role @@ -89,7 +89,7 @@ The following flags are required: | `-type` | string | Must be `aws-iam`. | | `-name` | string | A name of your choice. Must be unique among all auth methods. | | `-description` | string | A description of your choice. | -| `-config` | string | A JSON string containing the [configuration](/docs/security/acl/auth-methods/aws-iam#config-parameters) for the the auth method. | +| `-config` | string | A JSON string containing the [configuration](/consul/docs/security/acl/auth-methods/aws-iam#config-parameters) for the the auth method. | In the `-config` option, the following fields are required: @@ -117,9 +117,9 @@ service_prefix "" { The policy allows `node:write` for any node name, which is necessary because the Consul node names on ECS are not known until runtime. -You can add the policy in Consul using the [`consul acl policy create`](/commands/acl/policy/create) command or the [`[PUT] /v1/acl/policy`](/api-docs/acl/policies#create-a-policy) API endpoint. +You can add the policy in Consul using the [`consul acl policy create`](/consul/commands/acl/policy/create) command or the [`[PUT] /v1/acl/policy`](/consul/api-docs/acl/policies#create-a-policy) API endpoint. -After the policy is created, create a Consul role associated with the policy by using the [`consul acl role create`](/commands/acl/role/create) command or the [`[PUT] /v1/acl/role`](/api-docs/acl/roles#create-a-role) API endpoint. +After the policy is created, create a Consul role associated with the policy by using the [`consul acl role create`](/consul/commands/acl/role/create) command or the [`[PUT] /v1/acl/role`](/consul/api-docs/acl/roles#create-a-role) API endpoint. The following example shows how to use the Consul CLI to create the client policy and role. @@ -177,7 +177,7 @@ The following flags are required: | `-type` | string | Must be `aws-iam`. | | `-name` | string | A name of your choice. Must be unique among all auth methods. | | `-description` | string | A description of your choice. | -| `-config` | string | A JSON string containing the [configuration](/docs/security/acl/auth-methods/aws-iam#config-parameters) for the the auth method. | +| `-config` | string | A JSON string containing the [configuration](/consul/docs/security/acl/auth-methods/aws-iam#config-parameters) for the the auth method. | In the `-config` option, the following fields are required: @@ -336,7 +336,7 @@ Next, update the Consul client startup script with the `consul login` command an options for a secure configuration. The following is an example of the *additional* content to include in the `consul-client` startup script. Refer to the [install -page](/docs/ecs/manual/install#consul-client-container) for the remainder of the startup script and how to pass this +page](/consul/docs/ecs/manual/install#consul-client-container) for the remainder of the startup script and how to pass this script to the container. @@ -452,12 +452,12 @@ The following flags are passed to the `consul login` command: | Field name | Type | Description | | ------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------ | -| [`-http-addr`](/commands/login#http-addr) | string | HTTP(S) address of the Consul server. | -| [`-ca-file`](/commands/login#ca-file) | string | Path of the CA cert for Consul's HTTPS interface. Not required when using Consul servers on HCP. | +| [`-http-addr`](/consul/commands/login#http-addr) | string | HTTP(S) address of the Consul server. | +| [`-ca-file`](/consul/commands/login#ca-file) | string | Path of the CA cert for Consul's HTTPS interface. Not required when using Consul servers on HCP. | | `-partition` | string | The Consul Enterprise admin partition the auth method belongs to. | -| [`-type`](/commands/login#type) | string | The auth method type. Must be `aws-iam`. | -| [`-method`](/commands/login#type) | string | The auth method name. Must be the name of the auth method for ECS client tokens. | -| [`-meta`](/commands/login#meta) | string | Metadata to set in description of the created token. Should include the task id and cluster as shown. | +| [`-type`](/consul/commands/login#type) | string | The auth method type. Must be `aws-iam`. | +| [`-method`](/consul/commands/login#type) | string | The auth method name. Must be the name of the auth method for ECS client tokens. | +| [`-meta`](/consul/commands/login#meta) | string | Metadata to set in description of the created token. Should include the task id and cluster as shown. | | `-aws-region` | string | The AWS region where the task is running. | | `-aws-auto-bearer-token` | | Must be set to login to the AWS IAM auth method. | | `-aws-include-entity` | | Must be set to enable IAM role details. | @@ -466,14 +466,14 @@ The following table describes the additional fields that must be included in the | Field name | Type | Description | | ------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------ | -| [`encrypt`](/docs/agent/config/cli-flags#_encrypt) | string | Gossip encryption key | -| [`tls.defaults.ca_file`](/docs/agent/config/config-files#tls_defaults_ca_file) | string | Consul server CA cert for TLS verification. | -| [`acl.enabled`](/docs/agent/config/config-files#acl_enabled) | boolean | Enable ACLs for this agent. | -| [`acl.tokens.agent`](/docs/agent/config/config-files#acl_tokens_agent) | string | Consul client token which authorizes this agent with Consul servers. | -| [`partition`](/docs/agent/config/config-files#partition-1) | string | The Consul Enterprise admin partition this agent belongs to. | +| [`encrypt`](/consul/docs/agent/config/cli-flags#_encrypt) | string | Gossip encryption key | +| [`tls.defaults.ca_file`](/consul/docs/agent/config/config-files#tls_defaults_ca_file) | string | Consul server CA cert for TLS verification. | +| [`acl.enabled`](/consul/docs/agent/config/config-files#acl_enabled) | boolean | Enable ACLs for this agent. | +| [`acl.tokens.agent`](/consul/docs/agent/config/config-files#acl_tokens_agent) | string | Consul client token which authorizes this agent with Consul servers. | +| [`partition`](/consul/docs/agent/config/config-files#partition-1) | string | The Consul Enterprise admin partition this agent belongs to. | ### Configure Audit Logging -[Audit logging](/docs/enterprise/audit-logging) is supported on clients running Consul Enterprise with ACLs enabled. +[Audit logging](/consul/docs/enterprise/audit-logging) is supported on clients running Consul Enterprise with ACLs enabled. To enable audit logging, update the startup script to add an `audit` stanza to the Consul client configuration file. The following example modifies the `consul-client` startup script to configure audit logs to be written to the `stdout` of the `consul-client` container. @@ -508,12 +508,12 @@ The following table describes the fields that must be included to configure audi | Field name | Type | Description | | ------------------------------------------------------------------------------- | ------- | ------------------------------------------------------------------------------------ | -| [`audit.enabled`](/docs/agent/config/config-files#enabled) | boolean | Enable audit logging for this agent. | -| [`audit.sink`](/docs/agent/config/config-files#sink) | object | The audit logging sink for this agent. | +| [`audit.enabled`](/consul/docs/agent/config/config-files#enabled) | boolean | Enable audit logging for this agent. | +| [`audit.sink`](/consul/docs/agent/config/config-files#sink) | object | The audit logging sink for this agent. | ## Configure `consul-ecs-mesh-init` and `consul-ecs-health-sync` -The following *additional* options should be set in the [`CONSUL_ECS_CONFIG_JSON`](/docs/ecs/manual/install#consul_ecs_config_json) environment variable. When these options are specified, the `consul-ecs mesh-init` command will run the `consul login` command to obtain a service token from the Consul AWS IAM Auth method. The `consul-ecs health-sync` command is responsible for running a `consul logout` command for both the service and client tokens when the task shuts down. +The following *additional* options should be set in the [`CONSUL_ECS_CONFIG_JSON`](/consul/docs/ecs/manual/install#consul_ecs_config_json) environment variable. When these options are specified, the `consul-ecs mesh-init` command will run the `consul login` command to obtain a service token from the Consul AWS IAM Auth method. The `consul-ecs health-sync` command is responsible for running a `consul logout` command for both the service and client tokens when the task shuts down. diff --git a/website/content/docs/ecs/requirements.mdx b/website/content/docs/ecs/requirements.mdx index 4e7cca5c6c..4e4f997eac 100644 --- a/website/content/docs/ecs/requirements.mdx +++ b/website/content/docs/ecs/requirements.mdx @@ -14,16 +14,16 @@ The following requirements must be met in order to install Consul on ECS: * **Subnets:** ECS Tasks can run in private or public subnets. Tasks must have [network access](https://aws.amazon.com/premiumsupport/knowledge-center/ecs-pull-container-api-error-ecr/) to Amazon ECR or other public container registries to pull images. * **Consul Servers:** You can use your own Consul servers running on virtual machines or use [HashiCorp Cloud Platform Consul](https://www.hashicorp.com/cloud-platform) to host the servers for you. For development purposes or testing, you may use the `dev-server` [Terraform module](https://github.com/hashicorp/terraform-aws-consul-ecs/tree/main) that runs the Consul server as an ECS task. The `dev-server` does not support persistent storage. * **ACL Controller:** If you are running a secure Consul installation with ACLs enabled, configure the ACL controller. - * **Admin Partitions:** Consul on ECS supports [admin partitions](/docs/enterprise/admin-partitions) when ACLs are enabled and the ACL controller is configured. + * **Admin Partitions:** Consul on ECS supports [admin partitions](/consul/docs/enterprise/admin-partitions) when ACLs are enabled and the ACL controller is configured. The ACL controller manages one admin partition and each ECS cluster requires an ACL controller. Each `mesh-task` must also be configured to use a Consul Enterprise client. - * **Namespaces:** [Namespaces](/docs/enterprise/namespaces) are supported when ACLs are enabled and the ACL controller is configured. + * **Namespaces:** [Namespaces](/consul/docs/enterprise/namespaces) are supported when ACLs are enabled and the ACL controller is configured. Each `mesh-task` must also be configured to use a Consul Enterprise client. * **Sidecar containers:** Consul on ECS requires two sidecar containers to run in each ECS task: a Consul agent container and a sidecar proxy container. These additional sidecar containers must - be included in the ECS task definition. The [Consul ECS Terraform module](/docs/ecs/terraform/install) + be included in the ECS task definition. The [Consul ECS Terraform module](/consul/docs/ecs/terraform/install) will include these sidecar containers for you. If you do not use Terraform, you can construct - the task definition yourself by following [our documentation](/docs/ecs/manual/install). + the task definition yourself by following [our documentation](/consul/docs/ecs/manual/install). * **Routing:** With your application running in tasks as part of the mesh, you must specify the upstream services that your application calls. You will also need to change the URLs your application uses to ensure the application is making requests through the service mesh. diff --git a/website/content/docs/ecs/task-resource-usage.mdx b/website/content/docs/ecs/task-resource-usage.mdx index 30c334b2f3..8a566ad016 100644 --- a/website/content/docs/ecs/task-resource-usage.mdx +++ b/website/content/docs/ecs/task-resource-usage.mdx @@ -9,7 +9,7 @@ description: >- We ran performance tests of Consul on ECS to determine the resource usage of the sidecar containers Consul on ECS injects along with the ACL controller. -[The architecture page](/docs/ecs/architecture) describes each Consul on ECS +[The architecture page](/consul/docs/ecs/architecture) describes each Consul on ECS component in depth. We used the following procedure to measure resource usage: diff --git a/website/content/docs/ecs/terraform/install.mdx b/website/content/docs/ecs/terraform/install.mdx index 2c2c87e08f..3aa2dff4df 100644 --- a/website/content/docs/ecs/terraform/install.mdx +++ b/website/content/docs/ecs/terraform/install.mdx @@ -7,9 +7,9 @@ description: >- # Install Consul on AWS Elastic Container Service (ECS) with Terraform -This topic describes how to use HashiCorp's Terraform modules to launch your application in AWS ECS as part of Consul service mesh. If you do not use Terraform, refer to the [Manual Installation](/docs/ecs/manual/install) page to install Consul on ECS without Terraform. +This topic describes how to use HashiCorp's Terraform modules to launch your application in AWS ECS as part of Consul service mesh. If you do not use Terraform, refer to the [Manual Installation](/consul/docs/ecs/manual/install) page to install Consul on ECS without Terraform. -This topic does not include instructions for creating all AWS resources necessary to install Consul, such as a VPC or the ECS cluster. Refer to the guides in the [Getting Started](/docs/ecs#getting-started) section for complete and runnable examples. +This topic does not include instructions for creating all AWS resources necessary to install Consul, such as a VPC or the ECS cluster. Refer to the guides in the [Getting Started](/consul/docs/ecs#getting-started) section for complete and runnable examples. ## Overview @@ -22,13 +22,13 @@ The following procedure describes the general workflow: 2. [Run Terraform](#running-terraform) to deploy the resources in AWS -If you want to operate Consul in production environments, follow the instructions in the [Secure Configuration](/docs/ecs/terraform/secure-configuration) documentation. The instructions describe how to enable ACLs and TLS and gossip encryption, which provide network security for production-grade deployments. +If you want to operate Consul in production environments, follow the instructions in the [Secure Configuration](/consul/docs/ecs/terraform/secure-configuration) documentation. The instructions describe how to enable ACLs and TLS and gossip encryption, which provide network security for production-grade deployments. ## Requirements -* You should have some familiarity with using Terraform. Refer to the [Terraform documentation](https://www.terraform.io/docs) to learn about infrastructure as code and how to get started with Terraform. +* You should have some familiarity with using Terraform. Refer to the [Terraform documentation](/terraform/docs) to learn about infrastructure as code and how to get started with Terraform. * You should also be familiar with AWS ECS before following these instructions. See [What is Amazon Elastic Container Service](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/Welcome.html) for details. -* If you intend to [use the `gateway-task` module to deploy mesh gateways](#configure-the-gateway-task-module), all Consul server and client agents in all datacenters must have TLS and gossip encryption enabled. Refer to the [Secure Configuration](/docs/ecs/terraform/secure-configuration) documentation for instructions. +* If you intend to [use the `gateway-task` module to deploy mesh gateways](#configure-the-gateway-task-module), all Consul server and client agents in all datacenters must have TLS and gossip encryption enabled. Refer to the [Secure Configuration](/consul/docs/ecs/terraform/secure-configuration) documentation for instructions. ## Create the task definition @@ -88,7 +88,7 @@ The following fields are required. Refer to the [module reference documentation] | `container_definitions` | list | This is the list of [container definitions](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#container_definitions) for the task definition. This is where you include your application containers. | | `essential` | boolean | Must be `true` to ensure the health of your application container affects the health status of the task. | | `port` | integer | The port that your application listens on, if any. If your application does not listen on a port, set `outbound_only = true`. | -| `retry_join` | list | This is the [`retry_join`](/docs/agent/config/config-files#retry_join) option for the Consul agent, which specifies the locations of your Consul servers. | +| `retry_join` | list | This is the [`retry_join`](/consul/docs/agent/config/config-files#retry_join) option for the Consul agent, which specifies the locations of your Consul servers. | ### Configure an ECS service for the mesh task module [ECS services](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs_services.html) are one of the most common @@ -137,8 +137,8 @@ in their [`network_configuration`](https://registry.terraform.io/providers/hashi Add the `gateway-task` to your Terraform configuration if you want to deploy a mesh gateway. Mesh gateways enable service to service communication across the WAN, as well as federate service mesh traffic across Consul admin partitions and Consul datacenters over the WAN. Refer to the following documentation to learn more about mesh gateways: -* [WAN Federation via Mesh Gateways](/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways) -* [Service-to-service Traffic Across Datacenters](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters). +* [WAN Federation via Mesh Gateways](/consul/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways) +* [Service-to-service Traffic Across Datacenters](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters). You must add and configure a `gateway-task` for each Consul datacenter in your network. You must also enable TLS and gossip encryption on all server and client agents in all data centers per the [Requirements](#requirements). Mesh gateways operate by sniffing and extracting the server name indication (SNI) header from the service mesh session and routing the connection to the appropriate destination based on the server name requested. @@ -180,7 +180,7 @@ The following fields are required. Refer to the [module reference documentation] | `family` | string | Specifies the [ECS task definition family](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definition_parameters.html#family). The family is also used as the Consul service name by default. | | `ecs_cluster_arn` | string | Specifies the ARN of the ECS cluster where the mesh gateway task should be launched. | | `subnets` | list of strings | Specifies the subnet IDs where the task will be launched. | -| `retry_join` | list of strings | Defines a set of arguments to pass to the Consul agent [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) flag. The arguments specify locations of the Consul servers in the local datacenter that Consul client agents can connect to. | +| `retry_join` | list of strings | Defines a set of arguments to pass to the Consul agent [`-retry-join`](/consul/docs/agent/config/cli-flags#_retry_join) flag. The arguments specify locations of the Consul servers in the local datacenter that Consul client agents can connect to. | | `tls` | boolean | Set to `true` to enable TLS. | | `consul_server_ca_cert_arn` | string | Specifies the ARN of the Secrets Manager containing the Consul server CA certificate | | `gossip_key_secret_arn` | string | Specifies the ARN of the Secrets Manager containing the Consul's gossip encryption key. | @@ -195,7 +195,7 @@ The ECS service is automatically created by the `gateway-task` module. The servi The `mesh-init` container is a short-lived container that sets up the initial configurations for Consul and Envoy. The `gateway-task` module automatically configures the `mesh-init` container based on the inputs specified in the [task definition](#task-definition) and [ECS service](#ecs-service) configuration. -For additional information, refer to [Task Startup](/docs/ecs/architecture#task-startup) for additional information. +For additional information, refer to [Task Startup](/consul/docs/ecs/architecture#task-startup) for additional information. #### Gateway task configuration examples @@ -269,7 +269,7 @@ module "my_mesh_gateway" { ##### WAN federation -Configure the following options in the `gateway-task` to enable [WAN federation via mesh gateways](/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways). +Configure the following options in the `gateway-task` to enable [WAN federation via mesh gateways](/consul/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways). | Option | Type | Description | | --- | --- | --- | @@ -295,7 +295,7 @@ module "my_mesh_gateway" { -When federating Consul datacenters over the WAN with ACLs enabled, [ACL Token replication](/docs/security/acl/acl-federated-datacenters) must be enabled on all server and client agents in all datacenters. +When federating Consul datacenters over the WAN with ACLs enabled, [ACL Token replication](/consul/docs/security/acl/acl-federated-datacenters) must be enabled on all server and client agents in all datacenters. ## Run Terraform @@ -344,7 +344,7 @@ Terraform should be run in your project directory as follows. * Run `terraform apply` to have Terraform create AWS resources, such as the task definition from the `mesh-task` module. Terraform automatically reads all files in the current directory that have a `.tf` file extension. -Refer to the [Terraform documentation](https://www.terraform.io/docs) for more information and Terraform best practices. +Refer to the [Terraform documentation](/terraform/docs) for more information and Terraform best practices. ## Configure routes @@ -445,8 +445,8 @@ python manage.py runserver "$BIND_ADDRESS" ## Next steps -- Follow the [Secure Configuration](/docs/ecs/terraform/secure-configuration) to get production-ready. +- Follow the [Secure Configuration](/consul/docs/ecs/terraform/secure-configuration) to get production-ready. - Now that your applications are running in the service mesh, read about - other [Service Mesh features](/docs/connect). -- View the [Architecture](/docs/ecs/architecture) documentation to understand + other [Service Mesh features](/consul/docs/connect). +- View the [Architecture](/consul/docs/ecs/architecture) documentation to understand what's going on under the hood. diff --git a/website/content/docs/ecs/terraform/migrate-existing-tasks.mdx b/website/content/docs/ecs/terraform/migrate-existing-tasks.mdx index 2c17a1383c..5dcfb31e92 100644 --- a/website/content/docs/ecs/terraform/migrate-existing-tasks.mdx +++ b/website/content/docs/ecs/terraform/migrate-existing-tasks.mdx @@ -111,5 +111,5 @@ resource. Now that your task(s) are migrated to the `mesh-task` module, -- Start at the [ECS Service section](/docs/ecs/terraform/install#configure-an-ecs-service-for-the-mesh-task-module) of the Installation Guide to continue installing Consul on ECS. +- Start at the [ECS Service section](/consul/docs/ecs/terraform/install#configure-an-ecs-service-for-the-mesh-task-module) of the Installation Guide to continue installing Consul on ECS. - Refer to the [`mesh-task` reference documentation](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/mesh-task?tab=inputs) for all available inputs to your mesh tasks. diff --git a/website/content/docs/ecs/terraform/secure-configuration.mdx b/website/content/docs/ecs/terraform/secure-configuration.mdx index 979f98edc3..c1997241c3 100644 --- a/website/content/docs/ecs/terraform/secure-configuration.mdx +++ b/website/content/docs/ecs/terraform/secure-configuration.mdx @@ -11,7 +11,7 @@ This topic describes how to enable Consul security features for your production ## Overview -To enable security in your production workloads, you must deploy the [ACL controller](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/acl-controller), which provisions tokens for other service mesh tasks. Refer to [Architecture](/docs/ecs/architecture#acl-controller) to learn more about the ACL controller. +To enable security in your production workloads, you must deploy the [ACL controller](https://registry.terraform.io/modules/hashicorp/consul-ecs/aws/latest/submodules/acl-controller), which provisions tokens for other service mesh tasks. Refer to [Architecture](/consul/docs/ecs/architecture#acl-controller) to learn more about the ACL controller. The controller cannot provision tokens for itself, so you must create the token for the ACL controller. The following steps describe the overall process of enabling security features for your production workloads: @@ -26,13 +26,13 @@ The controller cannot provision tokens for itself, so you must create the token Implement the following security features for your Consul server clusters before applying them to your workloads: -1. [TLS encryption](/docs/security/encryption#rpc-encryption-with-tls) for RPC communication between Consul clients and servers. -1. [Gossip encryption](/docs/security/encryption#gossip-encryption) for encrypting gossip traffic. -1. [Access control lists (ACLs)](/docs/security/acl) for authentication and authorization for Consul clients and services on the mesh. +1. [TLS encryption](/consul/docs/security/encryption#rpc-encryption-with-tls) for RPC communication between Consul clients and servers. +1. [Gossip encryption](/consul/docs/security/encryption#gossip-encryption) for encrypting gossip traffic. +1. [Access control lists (ACLs)](/consul/docs/security/acl) for authentication and authorization for Consul clients and services on the mesh. ## Auth Method -Consul on ECS uses the [AWS IAM Auth Method](/docs/ecs/architecture#aws-iam-auth-method) to enable +Consul on ECS uses the [AWS IAM Auth Method](/consul/docs/ecs/architecture#aws-iam-auth-method) to enable tasks to automatically obtain Consul ACL tokens during startup. With the Terraform modules for Consul on ECS, the auth method is supported by default when ACLs are @@ -47,13 +47,13 @@ By default, the `mesh-task` module will create and configure the task IAM role f ~> **Note:** When passing an existing IAM role to the `mesh-task` module using the `task_role` input variable, you must configure the IAM role as described in [ECS Task Role -Configuration](/docs/ecs/manual/secure-configuration#ecs-task-role-configuration) to be compatible with +Configuration](/consul/docs/ecs/manual/secure-configuration#ecs-task-role-configuration) to be compatible with the AWS IAM auth method. ## ACL controller -1. Create a policy that grants `acl:write` and `operator:write` access for the controller. Refer to the [ACL policies documentation](/docs/security/acl/acl-policies) for instructions. -1. Create a token and link it to the ACL controller policy. Refer to the [ACL tokens documentation](/docs/security/acl/acl-tokens) for instructions. +1. Create a policy that grants `acl:write` and `operator:write` access for the controller. Refer to the [ACL policies documentation](/consul/docs/security/acl/acl-policies) for instructions. +1. Create a token and link it to the ACL controller policy. Refer to the [ACL tokens documentation](/consul/docs/security/acl/acl-tokens) for instructions. 1. Create a Secrets Manager secret containing the ACL controller's token and a Secrets Manager secret containing the Consul CA cert. ```hcl @@ -114,7 +114,7 @@ additional configuration required to support Consul Enterprise on ECS. ## Deploy your services -Follow the instructions described in [Create a task definition](/docs/ecs/terraform/install#create-the-task-definition) to create the basic configuration for the task module. Add the following additional configurations to make the configuration production-ready. +Follow the instructions described in [Create a task definition](/consul/docs/ecs/terraform/install#create-the-task-definition) to create the basic configuration for the task module. Add the following additional configurations to make the configuration production-ready. ### Create an AWS Secrets Manager secret @@ -171,6 +171,6 @@ The following table explains the `mesh-task` input variables relevant to a secur Complete the following steps described in the Installation with Terraform chapter to deploy and connect your services: -1. [Run Terraform](/docs/ecs/terraform/install#run-terraform) -1. [Configure routes](/docs/ecs/terraform/install#configure-routes) -1. [Configure the bind address](/docs/ecs/terraform/install#configure-the-bind-address) +1. [Run Terraform](/consul/docs/ecs/terraform/install#run-terraform) +1. [Configure routes](/consul/docs/ecs/terraform/install#configure-routes) +1. [Configure the bind address](/consul/docs/ecs/terraform/install#configure-the-bind-address) diff --git a/website/content/docs/enterprise/admin-partitions.mdx b/website/content/docs/enterprise/admin-partitions.mdx index ef6aa23bef..e5fdea32cf 100644 --- a/website/content/docs/enterprise/admin-partitions.mdx +++ b/website/content/docs/enterprise/admin-partitions.mdx @@ -11,7 +11,7 @@ description: >- This feature requires version 1.11.0+ of HashiCorp Cloud Platform (HCP) or self-managed Consul Enterprise. -Refer to the [enterprise feature matrix](/docs/enterprise#consul-enterprise-feature-availability) for additional information. +Refer to the [enterprise feature matrix](/consul/docs/enterprise#consul-enterprise-feature-availability) for additional information. @@ -27,8 +27,8 @@ As of Consul v1.11, every _datacenter_ contains a single administrative partitio There are tutorials available to help you get started with admin partitions. -- [Multi-Tenancy with Administrative Partitions](https://learn.hashicorp.com/tutorials/consul/consul-admin-partitions?utm_source=docs) -- [Multi Cluster Applications with Consul Enterprise Admin Partitions](https://learn.hashicorp.com/tutorials/consul/kubernetes-admin-partitions?utm_source=docs) +- [Multi-Tenancy with Administrative Partitions](/consul/tutorials/enterprise/consul-admin-partitions?utm_source=docs) +- [Multi Cluster Applications with Consul Enterprise Admin Partitions](/consul/tutorials/kubernetes/kubernetes-admin-partitions?utm_source=docs) ### Default Admin Partition @@ -57,17 +57,17 @@ Client agents will be configured to operate within a specific admin partition. T ### Service Mesh Configurations -The partition in which [`proxy-defaults`](/docs/connect/config-entries/proxy-defaults) and [`mesh`](/docs/connect/config-entries/mesh) configurations are created define the scope of the configurations. Services registered in a partition will use the `proxy-defaults` and `mesh` configurations that have been created in the partition. +The partition in which [`proxy-defaults`](/consul/docs/connect/config-entries/proxy-defaults) and [`mesh`](/consul/docs/connect/config-entries/mesh) configurations are created define the scope of the configurations. Services registered in a partition will use the `proxy-defaults` and `mesh` configurations that have been created in the partition. ### Cross-partition Networking -You can configure services to be discoverable by downstream services in any partition within the datacenter. Specify the upstream services that you want to be available for discovery by configuring the `exported-services` configuration entry in the partition where the services are registered. Refer to the [`exported-services` documentation](/docs/connect/config-entries/exported-services) for details. Additionally, the requests made by downstream applications must have the correct DNS name for the Virtual IP Service lookup to occur. Service Virtual IP lookups allow for communications across Admin Partitions when using Transparent Proxy. Refer to the [Service Virtual IP Lookups for Consul Enterprise](/docs/discovery/dns#service-virtual-ip-lookups-for-consul-enterprise) for additional information. +You can configure services to be discoverable by downstream services in any partition within the datacenter. Specify the upstream services that you want to be available for discovery by configuring the `exported-services` configuration entry in the partition where the services are registered. Refer to the [`exported-services` documentation](/consul/docs/connect/config-entries/exported-services) for details. Additionally, the requests made by downstream applications must have the correct DNS name for the Virtual IP Service lookup to occur. Service Virtual IP lookups allow for communications across Admin Partitions when using Transparent Proxy. Refer to the [Service Virtual IP Lookups for Consul Enterprise](/consul/docs/discovery/dns#service-virtual-ip-lookups-for-consul-enterprise) for additional information. ### Cluster Peering -You can use [cluster peering](/docs/connect/cluster-peering/) between two admin partitions to connect clusters owned by different operators. Without Consul Enterprise, cluster peering is limited to the `default` partitions in each datacenter. Enterprise users can [create and manage cluster peering connections](/docs/connect/cluster-peering/create-manage-peering) between any two admin partitions as long as the partitions are in separate datacenters. It is not possible to establish cluster peering connections between two partitions in a single datacenter. +You can use [cluster peering](/consul/docs/connect/cluster-peering/) between two admin partitions to connect clusters owned by different operators. Without Consul Enterprise, cluster peering is limited to the `default` partitions in each datacenter. Enterprise users can [create and manage cluster peering connections](/consul/docs/connect/cluster-peering/create-manage-peering) between any two admin partitions as long as the partitions are in separate datacenters. It is not possible to establish cluster peering connections between two partitions in a single datacenter. -To use mesh gateways with admin partitions and cluster peering, refer to [Mesh Gateways between Peered Clusters](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers). +To use mesh gateways with admin partitions and cluster peering, refer to [Mesh Gateways between Peered Clusters](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers). ## Requirements @@ -91,7 +91,7 @@ For other runtimes, refer to the documentation for your infrastructure environme ### Security Configurations - The agent token used by the client agent must allow `node:write` in the admin partition. -- The `write` permission for `proxy-defaults` requires `mesh:write`. See [Admin Partition Rules](/docs/security/acl/acl-rules#admin-partition-rules) for additional information. +- The `write` permission for `proxy-defaults` requires `mesh:write`. See [Admin Partition Rules](/consul/docs/security/acl/acl-rules#admin-partition-rules) for additional information. - The `write` permissions for ingress and terminating gateways require `mesh:write` privileges. - Wildcards (`*`) are not supported for the partition field when creating intentions for admin partitions. The partition name must be explicitly specified. - With the exception of the `default` admin partition, ACL rules configured for admin partitions are isolated, so policies defined in partitions outside of the `default` partition can only reference their local partition. @@ -125,7 +125,7 @@ One of the primary use cases for admin partitions is for enabling a service mesh ## Usage -This section describes how to deploy Consul admin partitions to Kubernetes clusters. Refer to the [admin partition CLI documentation](/commands/partition) for information about command line usage. +This section describes how to deploy Consul admin partitions to Kubernetes clusters. Refer to the [admin partition CLI documentation](/consul/commands/partition) for information about command line usage. ### Deploying Consul with Admin Partitions on Kubernetes @@ -195,7 +195,7 @@ Verify that your Consul deployment meets the [Kubernetes Requirements](#kubernet     - Refer to the [Helm Chart Configuration reference](/docs/k8s/helm) for details about the parameters you can specify in the file. + Refer to the [Helm Chart Configuration reference](/consul/docs/k8s/helm) for details about the parameters you can specify in the file. 1. Install the Consul server(s) using the values file created in the previous step: diff --git a/website/content/docs/enterprise/audit-logging.mdx b/website/content/docs/enterprise/audit-logging.mdx index 0d7c37fd31..14d87265bf 100644 --- a/website/content/docs/enterprise/audit-logging.mdx +++ b/website/content/docs/enterprise/audit-logging.mdx @@ -11,7 +11,7 @@ description: >- This feature requires HashiCorp Cloud Platform (HCP) or self-managed Consul Enterprise. -Refer to the [enterprise feature matrix](/docs/enterprise#consul-enterprise-feature-availability) for additional information. +Refer to the [enterprise feature matrix](/consul/docs/enterprise#consul-enterprise-feature-availability) for additional information.     @@ -23,17 +23,17 @@ and contain a timestamp, the operation performed, and the user who initiated the Audit logging enables security and compliance teams within an organization to get greater insight into Consul access and usage patterns. -Complete the [Capture Consul Events with Audit Logging](https://learn.hashicorp.com/tutorials/consul/audit-logging) tutorial to learn more about Consul's audit logging functionality, +Complete the [Capture Consul Events with Audit Logging](/consul/tutorials/datacenter-operations/audit-logging) tutorial to learn more about Consul's audit logging functionality, For detailed configuration information on configuring the Consul Enterprise's audit -logging, review the Consul [Audit Log](/docs/agent/config/config-files#audit) +logging, review the Consul [Audit Log](/consul/docs/agent/config/config-files#audit) documentation. ## Example Configuration Audit logging must be enabled on every agent in order to accurately capture all operations performed through the HTTP API. To enable logging, add -the [`audit`](/docs/agent/config/config-files#audit) stanza to the agent's configuration. +the [`audit`](/consul/docs/agent/config/config-files#audit) stanza to the agent's configuration. -> **Note**: Consul only logs operations which are initiated via the HTTP API. The audit log does not record operations that take place over the internal RPC @@ -137,7 +137,7 @@ is set to `OperationStart` which indicates the agent has begun processing the request. The value of the `payload.auth.accessor_id` field is the accessor ID of the -[ACL token](/docs/security/acl#tokens) which issued the request. +[ACL token](/consul/docs/security/acl#tokens) which issued the request. diff --git a/website/content/docs/enterprise/backups.mdx b/website/content/docs/enterprise/backups.mdx index 7f6321fa73..ba00952566 100644 --- a/website/content/docs/enterprise/backups.mdx +++ b/website/content/docs/enterprise/backups.mdx @@ -11,7 +11,7 @@ description: >- This feature requires HashiCorp Cloud Platform (HCP) or self-managed Consul Enterprise. -Refer to the [enterprise feature matrix](/docs/enterprise#consul-enterprise-feature-availability) for additional information. +Refer to the [enterprise feature matrix](/consul/docs/enterprise#consul-enterprise-feature-availability) for additional information.     @@ -33,6 +33,6 @@ datacenter backups include (but are not limited to): - Access Control Lists (ACLs) - Namespaces -For more experience leveraging Consul's snapshot functionality, complete the [Datacenter Backups in Consul](https://learn.hashicorp.com/tutorials/consul/backup-and-restore?utm_source=docs) tutorial. +For more experience leveraging Consul's snapshot functionality, complete the [Datacenter Backups in Consul](/consul/tutorials/production-deploy/backup-and-restore?utm_source=docs) tutorial. For detailed configuration information on configuring the Consul Enterprise's snapshot agent, review the -[Consul Snapshot Agent documentation](/commands/snapshot/agent). +[Consul Snapshot Agent documentation](/consul/commands/snapshot/agent). diff --git a/website/content/docs/enterprise/federation.mdx b/website/content/docs/enterprise/federation.mdx index 5296dbe119..9f84ef5d37 100644 --- a/website/content/docs/enterprise/federation.mdx +++ b/website/content/docs/enterprise/federation.mdx @@ -11,7 +11,7 @@ description: >- This feature requires self-managed Consul Enterprise. -Refer to the [enterprise feature matrix](/docs/enterprise#consul-enterprise-feature-availability) for additional information. +Refer to the [enterprise feature matrix](/consul/docs/enterprise#consul-enterprise-feature-availability) for additional information.     @@ -24,7 +24,7 @@ desirable to have topologies like hub-and-spoke with central management datacenters and "spoke" datacenters that can't interact with each other. [Consul Enterprise](https://www.hashicorp.com/consul) offers a [network -area mechanism](https://learn.hashicorp.com/tutorials/consul/federation-network-areas) that allows operators to +area mechanism](/consul/tutorials/datacenter-operations/federation-network-areas) that allows operators to federate Consul datacenters together on a pairwise basis, enabling partially-connected network topologies. Once a link is created, Consul agents can make queries to the remote datacenter in service of both API and DNS diff --git a/website/content/docs/enterprise/index.mdx b/website/content/docs/enterprise/index.mdx index a0f9b4c355..d03ab438d2 100644 --- a/website/content/docs/enterprise/index.mdx +++ b/website/content/docs/enterprise/index.mdx @@ -17,28 +17,28 @@ refer to [how to access Consul Enterprise](#access-consul-enterprise). The following features are [available in several forms of Consul Enterprise](#consul-enterprise-feature-availability). ### Multi-Tenancy -- [Admin Partitions](/docs/enterprise/admin-partitions): Define administrative boundaries between tenants within a single Consul datacenter -- [Namespaces](/docs/enterprise/namespaces): Define resource boundaries within a single admin partition for further organizational flexibility +- [Admin Partitions](/consul/docs/enterprise/admin-partitions): Define administrative boundaries between tenants within a single Consul datacenter +- [Namespaces](/consul/docs/enterprise/namespaces): Define resource boundaries within a single admin partition for further organizational flexibility ### Resiliency -- [Automated Backups](/docs/enterprise/backups): Configure the automatic backup of Consul state -- [Redundancy Zones](/docs/enterprise/redundancy): Deploy backup voting Consul servers to efficiently improve Consul fault tolerance +- [Automated Backups](/consul/docs/enterprise/backups): Configure the automatic backup of Consul state +- [Redundancy Zones](/consul/docs/enterprise/redundancy): Deploy backup voting Consul servers to efficiently improve Consul fault tolerance ### Scalability -- [Read Replicas](/docs/enterprise/read-scale): Deploy non-voting Consul servers to enhance the scalability of read requests +- [Read Replicas](/consul/docs/enterprise/read-scale): Deploy non-voting Consul servers to enhance the scalability of read requests ### Operational Simplification -- [Automated Upgrades](/docs/enterprise/upgrades): Ease upgrades by automating the transition from existing to newly deployed Consul servers -- [Consul-Terraform-Sync Enterprise](/docs/nia/enterprise): Leverage the enhanced network infrastructure automation capabilities of the enterprise version of Consul-Terraform-Sync +- [Automated Upgrades](/consul/docs/enterprise/upgrades): Ease upgrades by automating the transition from existing to newly deployed Consul servers +- [Consul-Terraform-Sync Enterprise](/consul/docs/nia/enterprise): Leverage the enhanced network infrastructure automation capabilities of the enterprise version of Consul-Terraform-Sync ### Complex Network Topology Support -- [Network Areas](/docs/enterprise/federation): Support complex network topologies between federated Consul datacenters with pairwise federation rather than full mesh federation -- [Network Segments](/docs/enterprise/network-segments/network-segments-overview): Support complex network topologies within a Consul datacenter by enforcing boundaries in Consul client gossip traffic +- [Network Areas](/consul/docs/enterprise/federation): Support complex network topologies between federated Consul datacenters with pairwise federation rather than full mesh federation +- [Network Segments](/consul/docs/enterprise/network-segments/network-segments-overview): Support complex network topologies within a Consul datacenter by enforcing boundaries in Consul client gossip traffic ### Governance -- [OIDC Auth Method](/docs/security/acl/auth-methods/oidc): Manage user access to Consul through an OIDC identity provider instead of Consul ACL tokens directly -- [Audit Logging](/docs/enterprise/audit-logging): Understand Consul access and usage patterns by reviewing access to the Consul HTTP API -- [Sentinel for KV](/docs/enterprise/sentinel): Policy-as-code framework for defining advanced key-value storage access control policies +- [OIDC Auth Method](/consul/docs/security/acl/auth-methods/oidc): Manage user access to Consul through an OIDC identity provider instead of Consul ACL tokens directly +- [Audit Logging](/consul/docs/enterprise/audit-logging): Understand Consul access and usage patterns by reviewing access to the Consul HTTP API +- [Sentinel for KV](/consul/docs/enterprise/sentinel): Policy-as-code framework for defining advanced key-value storage access control policies ## Access Consul Enterprise @@ -56,7 +56,7 @@ You can try out HCP Consul for free. Refer to the ### Self-Managed Consul To access Consul Enterprise in a self-managed installation, -[apply a purchased license](/docs/enterprise/license/overview) +[apply a purchased license](/consul/docs/enterprise/license/overview) to the Consul Enterprise binary that grants access to the desired features. Contact your [HashiCorp Support contact](https://support.hashicorp.com/) for a development license. @@ -72,18 +72,18 @@ Available Enterprise features per Consul form and license include: | Feature | [HashiCorp Cloud Platform (HCP) Consul] | [Consul Enterprise] | Legacy Consul Enterprise (module-based) | | -------------------------------------------------------- | --------------------------------------- | ------------------- | ------------------------------------------------- | | Consul servers as a managed service | Yes | No (self-managed) | No (self-managed) | -| [Admin Partitions](/docs/enterprise/admin-partitions) | All tiers | Yes | With Governance and Policy module | -| [Audit Logging](/docs/enterprise/audit-logging) | Standard tier and above | Yes | With Governance and Policy module | -| [Automated Server Backups](/docs/enterprise/backups) | All tiers | Yes | Yes | -| [Automated Server Upgrades](/docs/enterprise/upgrades) | All tiers | Yes | Yes | -| [Consul-Terraform-Sync Enterprise](/docs/nia/enterprise) | All tiers | Yes | Yes | -| [Enhanced Read Scalability](/docs/enterprise/read-scale) | No | Yes | With Global Visibility, Routing, and Scale module | -| [Namespaces](/docs/enterprise/namespaces) | All tiers | Yes | With Governance and Policy module | -| [Network Areas](/docs/enterprise/federation) | No | Yes | With Global Visibility, Routing, and Scale module | -| [Network Segments](/docs/enterprise/network-segments/network-segments-overview) | No | Yes | With Global Visibility, Routing, and Scale module | -| [OIDC Auth Method](/docs/security/acl/auth-methods/oidc) | No | Yes | Yes | -| [Redundancy Zones](/docs/enterprise/redundancy) | Not applicable | Yes | With Global Visibility, Routing, and Scale module | -| [Sentinel for KV](/docs/enterprise/sentinel) | All tiers | Yes | With Governance and Policy module | +| [Admin Partitions](/consul/docs/enterprise/admin-partitions) | All tiers | Yes | With Governance and Policy module | +| [Audit Logging](/consul/docs/enterprise/audit-logging) | Standard tier and above | Yes | With Governance and Policy module | +| [Automated Server Backups](/consul/docs/enterprise/backups) | All tiers | Yes | Yes | +| [Automated Server Upgrades](/consul/docs/enterprise/upgrades) | All tiers | Yes | Yes | +| [Consul-Terraform-Sync Enterprise](/consul/docs/nia/enterprise) | All tiers | Yes | Yes | +| [Enhanced Read Scalability](/consul/docs/enterprise/read-scale) | No | Yes | With Global Visibility, Routing, and Scale module | +| [Namespaces](/consul/docs/enterprise/namespaces) | All tiers | Yes | With Governance and Policy module | +| [Network Areas](/consul/docs/enterprise/federation) | No | Yes | With Global Visibility, Routing, and Scale module | +| [Network Segments](/consul/docs/enterprise/network-segments/network-segments-overview) | No | Yes | With Global Visibility, Routing, and Scale module | +| [OIDC Auth Method](/consul/docs/security/acl/auth-methods/oidc) | No | Yes | Yes | +| [Redundancy Zones](/consul/docs/enterprise/redundancy) | Not applicable | Yes | With Global Visibility, Routing, and Scale module | +| [Sentinel for KV](/consul/docs/enterprise/sentinel) | All tiers | Yes | With Governance and Policy module | [HashiCorp Cloud Platform (HCP) Consul]: https://cloud.hashicorp.com/products/consul [Consul Enterprise]: https://www.hashicorp.com/products/consul/ diff --git a/website/content/docs/enterprise/license/faq.mdx b/website/content/docs/enterprise/license/faq.mdx index 480d696ca0..02841e9c6c 100644 --- a/website/content/docs/enterprise/license/faq.mdx +++ b/website/content/docs/enterprise/license/faq.mdx @@ -26,23 +26,23 @@ This will no longer work since each server must be able to find a valid license All customers on Consul Enterprise 1.8/1.9 must first upgrade their client and server agents to the latest patch release. During the upgrade the license file must also be configured on client agents in an environment variable or file path, otherwise the Consul agents will fail to retrieve the license with a valid agent token. The upgrade process varies if ACLs are enabled or disabled in the cluster. -Refer to the instructions on [upgrading to 1.10.x](/docs/upgrading/instructions/upgrade-to-1-10-x) for details. +Refer to the instructions on [upgrading to 1.10.x](/consul/docs/upgrading/instructions/upgrade-to-1-10-x) for details. ## Q: Is there a tutorial available for the license configuration steps? -Please visit the [Enterprise License Tutorial](https://learn.hashicorp.com/tutorials/nomad/hashicorp-enterprise-license?utm_source=docs). +Please visit the [Enterprise License Tutorial](/nomad/tutorials/enterprise/hashicorp-enterprise-license?utm_source=docs). ## Q: What resources are available? The list below is a great starting point for learning more about the license changes introduced in Consul Enterprise 1.10.0+ent. -- [Consul Enterprise Upgrade Documentation](/docs/enterprise/upgrades) +- [Consul Enterprise Upgrade Documentation](/consul/docs/enterprise/upgrades) -- [Consul License Documentation](/docs/enterprise/license/overview) +- [Consul License Documentation](/consul/docs/enterprise/license/overview) -- [License configuration values documentation](/docs/enterprise/license/overview#binaries-without-built-in-licenses) +- [License configuration values documentation](/consul/docs/enterprise/license/overview#binaries-without-built-in-licenses) -- [Install a HashiCorp Enterprise License Tutorial](https://learn.hashicorp.com/tutorials/nomad/hashicorp-enterprise-license?utm_source=docs) +- [Install a HashiCorp Enterprise License Tutorial](/nomad/tutorials/enterprise/hashicorp-enterprise-license?utm_source=docs) ## Q: Do these changes impact all customers/licenses? @@ -65,12 +65,12 @@ can operate without a license. ## Q: Is there a grace period when licenses expire? **Yes—Consul will continue normal operation and can be restarted after license *expiration*** as defined in -[`expiration_time`](/api-docs/operator/license#getting-the-consul-license). +[`expiration_time`](/consul/api-docs/operator/license#getting-the-consul-license). As license expiration is approached or passed, Consul will issue warnings in the system logs. Consul will only cease operation after license *termination*, which occurs 10 years after license expiration and is defined in -[`termination_time`](/api-docs/operator/license#getting-the-consul-license). +[`termination_time`](/consul/api-docs/operator/license#getting-the-consul-license). ~> **Starting with Consul 1.14, and patch releases 1.13.3 and 1.12.6, Consul will support non-terminating licenses**: Please contact your support representative for more details on non-terminating licenses. @@ -136,27 +136,27 @@ When a customer deploys new clusters to a 1.10.0+ent release, they need to have New Consul cluster deployments using 1.10.0+ent will need to have a valid license on servers to successfully deploy. This valid license must be on-disk (auto-loaded) or as an environment variable. -Please see the [upgrade requirements](faq#q-what-are-the-upgrade-requirements). +Please see the [upgrade requirements](https://consul.io/faq#q-what-are-the-upgrade-requirements). ## Q: What is the migration path for customers who want to migrate from their existing license-as-applied-via-the-CLI flow to the license on disk flow? ### VM -1. Run [`consul license get -signed`](/commands/license#get) to extract the license from their running cluster. Store the license in a secure location on disk. +1. Run [`consul license get -signed`](/consul/commands/license#get) to extract the license from their running cluster. Store the license in a secure location on disk. 1. Set up the necessary configuration so that when Consul Enterprise reboots it will have access to the required license. This could be via the client agent configuration file or an environment variable. -1. Visit the [Enterprise License Tutorial](https://learn.hashicorp.com/tutorials/nomad/hashicorp-enterprise-license?utm_source=docs) for detailed steps on how to install the license key. -1. Follow the Consul upgrade [documentation](/docs/upgrading). +1. Visit the [Enterprise License Tutorial](/nomad/tutorials/enterprise/hashicorp-enterprise-license?utm_source=docs) for detailed steps on how to install the license key. +1. Follow the Consul upgrade [documentation](/consul/docs/upgrading). ### Kubernetes **NOTE:** If you are not upgrading Consul or your Helm chart version then no action is required. 1. In order to use Consul Enterprise 1.10.0 or greater on Kubernetes you must use version 0.32.0 or greater of the Helm chart. -1. You should already have a Consul Enterprise license set as a Kubernetes secret. If you do not, refer to [how to obtain a copy of your license](/docs/enterprise/license/faq#q-i-m-an-existing-enterprise-customer-but-don-t-have-my-license-how-can-i-get-it). -Once you have the license then create a Kubernetes secret containing the license as described in [Kubernetes - Consul Enterprise](/docs/k8s/deployment-configurations/consul-enterprise). -1. Follow the [Kubernetes Upgrade Docs](/docs/k8s/upgrade) to upgrade. No changes to your `values.yaml` file are needed to enable enterprise autoloading since this support is built in to consul-helm 0.32.0 and greater. +1. You should already have a Consul Enterprise license set as a Kubernetes secret. If you do not, refer to [how to obtain a copy of your license](/consul/docs/enterprise/license/faq#q-i-m-an-existing-enterprise-customer-but-don-t-have-my-license-how-can-i-get-it). +Once you have the license then create a Kubernetes secret containing the license as described in [Kubernetes - Consul Enterprise](/consul/docs/k8s/deployment-configurations/consul-enterprise). +1. Follow the [Kubernetes Upgrade Docs](/consul/docs/k8s/upgrade) to upgrade. No changes to your `values.yaml` file are needed to enable enterprise autoloading since this support is built in to consul-helm 0.32.0 and greater. -!> **Warning:** If you are upgrading the Helm chart but **not** upgrading the Consul version, you must set `server.enterpriseLicense.enableLicenseAutoload: false`. See [Kubernetes - Consul Enterprise](/docs/k8s/deployment-configurations/consul-enterprise) for more details. +!> **Warning:** If you are upgrading the Helm chart but **not** upgrading the Consul version, you must set `server.enterpriseLicense.enableLicenseAutoload: false`. See [Kubernetes - Consul Enterprise](/consul/docs/k8s/deployment-configurations/consul-enterprise) for more details. ## Q: What is the migration path for customers who want to migrate from their existing perpetually-licensed binaries to the license on disk flow? @@ -165,15 +165,15 @@ Once you have the license then create a Kubernetes secret containing the license 1. Acquire a valid Consul Enterprise license. If you are an existing HashiCorp enterprise customer you may contact your organization's [customer success manager](https://support.hashicorp.com/hc/en-us) (CSM) for information on how to get your organization's enterprise license. 1. Store the license in a secure location on disk. 1. Set up the necessary configuration so that when Consul Enterprise reboots it will have the required license. This could be via the client agent configuration file or an environment variable. - Visit the [Enterprise License Tutorial](https://learn.hashicorp.com/tutorials/nomad/hashicorp-enterprise-license?utm_source=docs) for detailed steps on how to install the license key. -1. Follow the Consul upgrade [documentation](/docs/upgrading). + Visit the [Enterprise License Tutorial](/nomad/tutorials/enterprise/hashicorp-enterprise-license?utm_source=docs) for detailed steps on how to install the license key. +1. Follow the Consul upgrade [documentation](/consul/docs/upgrading). ### Kubernetes 1. Acquire a valid Consul Enterprise license. If you are an existing HashiCorp enterprise customer you may contact your organization's [customer success manager](https://support.hashicorp.com/hc/en-us) (CSM) for information on how to get your organization's enterprise license. 1. Set up the necessary configuration so that when Consul Enterprise reboots it will have the required license. This could be via the client agent configuration file or an environment variable. - Visit the [Enterprise License Tutorial](https://learn.hashicorp.com/tutorials/nomad/hashicorp-enterprise-license?utm_source=docs) for detailed steps on how to install the license key. -1. Proceed with the `helm` [upgrade instructions](/docs/k8s/upgrade) + Visit the [Enterprise License Tutorial](/nomad/tutorials/enterprise/hashicorp-enterprise-license?utm_source=docs) for detailed steps on how to install the license key. +1. Proceed with the `helm` [upgrade instructions](/consul/docs/k8s/upgrade) ## Q: Will Consul downgrades/rollbacks work? @@ -181,7 +181,7 @@ When downgrading to a version of Consul before 1.10.0+ent, customers will need t ## Q: Are there potential pitfalls when downgrading or upgrading Consul server instances? -~> Verify that you meet the [upgrade requirements](faq#q-what-are-the-upgrade-requirements). +~> Verify that you meet the [upgrade requirements](https://consul.io/faq#q-what-are-the-upgrade-requirements). Assume a scenario where there are three Consul server nodes: diff --git a/website/content/docs/enterprise/license/overview.mdx b/website/content/docs/enterprise/license/overview.mdx index 2cb75961e4..d2bcb88a4a 100644 --- a/website/content/docs/enterprise/license/overview.mdx +++ b/website/content/docs/enterprise/license/overview.mdx @@ -23,12 +23,12 @@ when it is started. Consul Enterprise 1.14.0, when running on Kubernetes, removed client agents and replaced these with virtual agents. Virtual agents are nodes that Consul service mesh services run on. HashiCorp uses virtual agents to determine license entitlements for customers on per-node licensing and pricing agreements. --> Visit the [Enterprise License Tutorial](https://learn.hashicorp.com/tutorials/nomad/hashicorp-enterprise-license?utm_source=docs) for detailed steps on how to install the license key. +-> Visit the [Enterprise License Tutorial](/nomad/tutorials/enterprise/hashicorp-enterprise-license?utm_source=docs) for detailed steps on how to install the license key. ### Applying a License For Consul Enterprise 1.10.0 or greater, a license must be available at the time the agent starts. -For server agents this means that they must either have the [`license_path`](/docs/agent/config/config-files#license_path) +For server agents this means that they must either have the [`license_path`](/consul/docs/agent/config/config-files#license_path) configuration set or have a license configured in the servers environment with the `CONSUL_LICENSE` or `CONSUL_LICENSE_PATH` environment variables. Both the configuration item and the `CONSUL_LICENSE_PATH` environment variable point to a file containing the license whereas the `CONSUL_LICENSE` environment @@ -39,7 +39,7 @@ the following order of precedence applies: 2. `CONSUL_LICENSE_PATH` environment variable 3. `license_path` configuration item. -Client agents and [snapshot agents](/docs/enterprise/backups) +Client agents and [snapshot agents](/consul/docs/enterprise/backups) may also be licensed in the very same manner. However, to avoid the need to configure the license on many client agents and snapshot agents, those agents have the capability to retrieve the license automatically under the conditions described below. @@ -51,7 +51,7 @@ Updating the license for an agent depends on the method you used to apply the li environment variable**: After updating the environment variable, restart the affected agents. - **If you used the `CONSUL_LICENSE_PATH` environment variable**: Update the license file first. Then, restart the affected agents. -- **If you used the `license_path` configuration item**: Update the license file first. Then, run [`consul reload`](/commands/reload) for the affected agents. +- **If you used the `license_path` configuration item**: Update the license file first. Then, run [`consul reload`](/consul/commands/reload) for the affected agents. #### Client Agent License Retrieval @@ -59,8 +59,8 @@ When a client agent starts without a license in its configuration or environment license from the servers via RPCs. That RPC always requires a valid non-anonymous ACL token to authorize the request but the token doesn't need any particular permissions. As the license is required before the client actually joins the cluster, where to make those RPC requests to is inferred from the -[`retry_join`](/docs/agent/config/config-files#retry_join) configuration. If `retry_join` is unset or no -[`agent` token](/docs/agent/config/config-files#acl_tokens_agent) is set then the client agent will immediately shut itself down. +[`retry_join`](/consul/docs/agent/config/config-files#retry_join) configuration. If `retry_join` is unset or no +[`agent` token](/consul/docs/agent/config/config-files#acl_tokens_agent) is set then the client agent will immediately shut itself down. If all preliminary checks pass the client agent will attempt to reach out to any server on its RPC port to request the license. These requests will be retried for up to 5 minutes and if it is unable to retrieve a diff --git a/website/content/docs/enterprise/namespaces.mdx b/website/content/docs/enterprise/namespaces.mdx index 374dedf269..d692ee4b9d 100644 --- a/website/content/docs/enterprise/namespaces.mdx +++ b/website/content/docs/enterprise/namespaces.mdx @@ -11,7 +11,7 @@ description: >- This feature requires HashiCorp Cloud Platform (HCP) or self-managed Consul Enterprise. -Refer to the [enterprise feature matrix](/docs/enterprise#consul-enterprise-feature-availability) for additional information. +Refer to the [enterprise feature matrix](/consul/docs/enterprise#consul-enterprise-feature-availability) for additional information.     @@ -22,12 +22,12 @@ to provide self-service through delegation of administrative privileges. For more information on how to use namespaces with Consul Enterprise please review the following tutorials: -- [Register and Discover Services within Namespaces](https://learn.hashicorp.com/tutorials/consul/namespaces-share-datacenter-access?utm_source=docs) - Register multiple services within different namespaces in Consul. -- [Setup Secure Namespaces](https://learn.hashicorp.com/tutorials/consul/namespaces-secure-shared-access?utm_source=docs) - Secure resources within a namespace and delegate namespace ACL rights via ACL tokens. +- [Register and Discover Services within Namespaces](/consul/tutorials/namespaces/namespaces-share-datacenter-access?utm_source=docs) - Register multiple services within different namespaces in Consul. +- [Setup Secure Namespaces](/consul/tutorials/namespaces/namespaces-secure-shared-access?utm_source=docs) - Secure resources within a namespace and delegate namespace ACL rights via ACL tokens. ## Namespace Definition -Namespaces are managed exclusively through the [HTTP API](/api-docs/namespaces) and the [Consul CLI](/commands/namespace). +Namespaces are managed exclusively through the [HTTP API](/consul/api-docs/namespaces) and the [Consul CLI](/consul/commands/namespace). The HTTP API accepts only JSON formatted definitions while the CLI will parse either JSON or HCL. An example namespace definition looks like the following: @@ -105,14 +105,14 @@ Meta { policies ID is omitted Consul will resolve the name to an ID before writing the namespace definition internally. Note that all policies linked in a namespace definition must be defined within the `default` namespace, and the ACL token used to create or edit the - namespace must have [`acl:write` access](/docs/security/acl/acl-rules#acl-resource-rules) to the linked policy. + namespace must have [`acl:write` access](/consul/docs/security/acl/acl-rules#acl-resource-rules) to the linked policy. - `RoleDefaults` `(array)` - A list of default roles to be applied to all tokens created in this namespace. The ACLLink object can contain an `ID` and/or `Name` field. When the roles' ID is omitted Consul will resolve the name to an ID before writing the namespace definition internally. Note that all roles linked in a namespace definition must be defined within the `default` namespace, and the ACL token used to create or edit the - namespace must have [`acl:write` access](/docs/security/acl/acl-rules#acl-resource-rules) to the linked role. + namespace must have [`acl:write` access](/consul/docs/security/acl/acl-rules#acl-resource-rules) to the linked role. - `Meta` `(map: )` - Specifies arbitrary KV metadata to associate with this namespace. diff --git a/website/content/docs/enterprise/network-segments/network-segments-overview.mdx b/website/content/docs/enterprise/network-segments/network-segments-overview.mdx index 565739b60d..2cae25636c 100644 --- a/website/content/docs/enterprise/network-segments/network-segments-overview.mdx +++ b/website/content/docs/enterprise/network-segments/network-segments-overview.mdx @@ -42,7 +42,7 @@ Read the [Network Segments documentation](/consul/docs/enterprise/network-segmen -> **Info:** Network segments enable you to operate a Consul datacenter without full mesh (LAN) connectivity between agents. To federate multiple Consul datacenters without full mesh (WAN) connectivity between all server agents in all datacenters, -use [Network Areas (Enterprise)](/docs/enterprise/federation). +use [Network Areas (Enterprise)](/consul/docs/enterprise/federation). ## Consul networking models diff --git a/website/content/docs/enterprise/read-scale.mdx b/website/content/docs/enterprise/read-scale.mdx index ee881bce6e..f4357d301e 100644 --- a/website/content/docs/enterprise/read-scale.mdx +++ b/website/content/docs/enterprise/read-scale.mdx @@ -11,7 +11,7 @@ description: >- This feature requires HashiCorp Cloud Platform (HCP) or self-managed Consul Enterprise. -Refer to the [enterprise feature matrix](/docs/enterprise#consul-enterprise-feature-availability) for additional information. +Refer to the [enterprise feature matrix](/consul/docs/enterprise#consul-enterprise-feature-availability) for additional information.     @@ -20,6 +20,6 @@ to include voting servers and read replicas. Read replicas still receive data fr however, they do not take part in quorum election operations. Expanding your Consul cluster in this way can scale reads without impacting write latency. -For more details, review the [Consul server configuration](/docs/agent/config) -documentation and the [-read-replica](/docs/agent/config/cli-flags#_read_replica) +For more details, review the [Consul server configuration](/consul/docs/agent/config) +documentation and the [-read-replica](/consul/docs/agent/config/cli-flags#_read_replica) configuration flag. diff --git a/website/content/docs/enterprise/redundancy.mdx b/website/content/docs/enterprise/redundancy.mdx index def48fb988..8d68b6b43a 100644 --- a/website/content/docs/enterprise/redundancy.mdx +++ b/website/content/docs/enterprise/redundancy.mdx @@ -11,7 +11,7 @@ description: >- This feature requires self-managed Consul Enterprise. -Refer to the [enterprise feature matrix](/docs/enterprise#consul-enterprise-feature-availability) for additional information. +Refer to the [enterprise feature matrix](/consul/docs/enterprise#consul-enterprise-feature-availability) for additional information.     @@ -26,8 +26,8 @@ promote the non-voting member to a voting member. In the event that an entire av zone was lost, a non-voting member in one of the existing availability zones would promote to a voting member, keeping server quorum. This capability functions as a "hot standby" for server nodes while also providing (and expanding) the capabilities of -[enhanced read scalability](/docs/enterprise/read-scale) by also including recovery +[enhanced read scalability](/consul/docs/enterprise/read-scale) by also including recovery capabilities. -For more information, complete the [Redundancy Zones](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations#redundancy-zones) tutorial -and reference the [Consul Autopilot](/commands/operator/autopilot) documentation. +For more information, complete the [Redundancy Zones](/consul/tutorials/datacenter-operations/autopilot-datacenter-operations#redundancy-zones) tutorial +and reference the [Consul Autopilot](/consul/commands/operator/autopilot) documentation. diff --git a/website/content/docs/enterprise/sentinel.mdx b/website/content/docs/enterprise/sentinel.mdx index 0697a569db..3fea0c8a9d 100644 --- a/website/content/docs/enterprise/sentinel.mdx +++ b/website/content/docs/enterprise/sentinel.mdx @@ -11,7 +11,7 @@ description: >- This feature requires HashiCorp Cloud Platform (HCP) or self-managed Consul Enterprise. -Refer to the [enterprise feature matrix](/docs/enterprise#consul-enterprise-feature-availability) for additional information. +Refer to the [enterprise feature matrix](/consul/docs/enterprise#consul-enterprise-feature-availability) for additional information.     @@ -21,4 +21,4 @@ external systems. Reference the [Sentinel documentation](https://docs.hashicorp. To get started with Sentinel in Consul, [read the general documentation](https://docs.hashicorp.com/sentinel/consul) or -[Consul documentation](/docs/agent/sentinel). +[Consul documentation](/consul/docs/agent/sentinel). diff --git a/website/content/docs/enterprise/upgrades.mdx b/website/content/docs/enterprise/upgrades.mdx index 23c11ea9bb..73b6648fed 100644 --- a/website/content/docs/enterprise/upgrades.mdx +++ b/website/content/docs/enterprise/upgrades.mdx @@ -15,7 +15,7 @@ description: >- This feature requires HashiCorp Cloud Platform (HCP) or self-managed Consul Enterprise. -Refer to the [enterprise feature matrix](/docs/enterprise#consul-enterprise-feature-availability) for additional information. +Refer to the [enterprise feature matrix](/consul/docs/enterprise#consul-enterprise-feature-availability) for additional information.     @@ -25,4 +25,4 @@ currently in a cluster. When an equal amount of new server nodes are joined runn will be demoted to non voting members. Demotion of legacy server nodes will not occur until the voting members on the new version match. Once this demotion occurs, the previous versioned servers can be removed from the cluster safely. -Review the [Consul operator autopilot](/commands/operator/autopilot) documentation and complete the [Automated Upgrade](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations#upgrade-migrations) tutorial to learn more about automated upgrades. +Review the [Consul operator autopilot](/consul/commands/operator/autopilot) documentation and complete the [Automated Upgrade](/consul/tutorials/datacenter-operations/autopilot-datacenter-operations#upgrade-migrations) tutorial to learn more about automated upgrades. diff --git a/website/content/docs/guides/index.mdx b/website/content/docs/guides/index.mdx index 744cf2ee93..02427c8b44 100644 --- a/website/content/docs/guides/index.mdx +++ b/website/content/docs/guides/index.mdx @@ -9,9 +9,9 @@ description: |- # Consul Guides -~> The Consul guides are now Consul [tutorials](https://learn.hashicorp.com/consul). +~> The Consul guides are now Consul [tutorials](/consul/tutorials). -[Guides](https://learn.hashicorp.com/consul) are step by step command-line +[Guides](/consul/tutorials) are step by step command-line walkthroughs that demonstrate how to perform common operations using Consul, and complement the feature-focused Consul documentation. diff --git a/website/content/docs/index.mdx b/website/content/docs/index.mdx index 8dd869b1e3..8477ac18ab 100644 --- a/website/content/docs/index.mdx +++ b/website/content/docs/index.mdx @@ -10,6 +10,6 @@ description: >- The Consul documentation provides reference material for all features and options available in Consul. Click the following links to access documentation and tutorials for common tasks: -- [Install Consul](/docs/install) -- [Configuration options](/docs/agent/config) -- [Step-by-step tutorials](https://learn.hashicorp.com/consul) +- [Install Consul](/consul/docs/install) +- [Configuration options](/consul/docs/agent/config) +- [Step-by-step tutorials](/consul/tutorials) diff --git a/website/content/docs/install/bootstrapping.mdx b/website/content/docs/install/bootstrapping.mdx index 5efe4ad93b..a991840204 100644 --- a/website/content/docs/install/bootstrapping.mdx +++ b/website/content/docs/install/bootstrapping.mdx @@ -8,34 +8,34 @@ description: >- # Bootstrap a Datacenter An agent can run in either client or server mode. Server nodes are responsible for running the -[consensus protocol](/docs/architecture/consensus) and storing the cluster state. +[consensus protocol](/consul/docs/architecture/consensus) and storing the cluster state. The client nodes are mostly stateless and rely heavily on the server nodes. Before a Consul cluster can begin to service requests, a server node must be elected leader. Bootstrapping is the process of joining these initial server nodes into a cluster. Read the -[architecture documentation](/docs/architecture) to learn more about +[architecture documentation](/consul/docs/architecture) to learn more about the internals of Consul. It is recommended to have three or five total servers per datacenter. A single server deployment is _highly_ discouraged as data loss is inevitable in a failure scenario. Please refer to the -[deployment table](/docs/architecture/consensus#deployment-table) for more detail. +[deployment table](/consul/docs/architecture/consensus#deployment-table) for more detail. ~> **Note**: In versions of Consul prior to 0.4, bootstrapping was a manual process. For details on using the `-bootstrap` flag directly, see the -[manual bootstrapping documentation](/docs/install/bootstrapping#manually-join-the-servers). +[manual bootstrapping documentation](/consul/docs/install/bootstrapping#manually-join-the-servers). Manual bootstrapping with `-bootstrap` is not recommended in newer versions of Consul (0.5 and newer) as it is more error-prone. Instead you should use automatic bootstrapping -with [`-bootstrap-expect`](/docs/agent/config/cli-flags#_bootstrap_expect). +with [`-bootstrap-expect`](/consul/docs/agent/config/cli-flags#_bootstrap_expect). ## Bootstrapping the Servers -The recommended way to bootstrap the servers is to use the [`-bootstrap-expect`](/docs/agent/config/cli-flags#_bootstrap_expect) +The recommended way to bootstrap the servers is to use the [`-bootstrap-expect`](/consul/docs/agent/config/cli-flags#_bootstrap_expect) configuration option. This option informs Consul of the expected number of server nodes and automatically bootstraps when that many servers are available. To prevent inconsistencies and split-brain (clusters where multiple servers consider themselves leader) situations, you should either specify the same value for -[`-bootstrap-expect`](/docs/agent/config/cli-flags#_bootstrap_expect) +[`-bootstrap-expect`](/consul/docs/agent/config/cli-flags#_bootstrap_expect) or specify no value at all on all the servers. Only servers that specify a value will attempt to bootstrap the cluster. Suppose we are starting a three server cluster. We can start `Node A`, `Node B`, and `Node C` with each @@ -56,8 +56,8 @@ You can trigger leader election by joining the servers together, to create a clu There are two options for joining the servers. Choose the method which best suits your environment and specific use case. -- Specify a list of servers with [-retry-join](/docs/agent/config/cli-flags#_retry_join) option. -- Use automatic joining by tag for supported cloud environments with the [-retry-join](/docs/agent/config/cli-flags#_retry_join) option. +- Specify a list of servers with [-retry-join](/consul/docs/agent/config/cli-flags#_retry_join) option. +- Use automatic joining by tag for supported cloud environments with the [-retry-join](/consul/docs/agent/config/cli-flags#_retry_join) option. All three methods can be set in the agent configuration file or the command line flag. @@ -84,10 +84,10 @@ Since a join operation is symmetric, it does not matter which node initiates it. ### Verifying the Cluster and Connect the Clients -As a sanity check, the [`consul info`](/commands/info) command +As a sanity check, the [`consul info`](/consul/commands/info) command is a useful tool. It can be used to verify the `raft.num_peers` and to view the latest log index under `raft.last_log_index`. When -running [`consul info`](/commands/info) on the followers, you +running [`consul info`](/consul/commands/info) on the followers, you should see `raft.last_log_index` converge to the same value once the leader begins replication. That value represents the last log entry that has been stored on disk. diff --git a/website/content/docs/install/cloud-auto-join.mdx b/website/content/docs/install/cloud-auto-join.mdx index efc0239960..40e2f44edf 100644 --- a/website/content/docs/install/cloud-auto-join.mdx +++ b/website/content/docs/install/cloud-auto-join.mdx @@ -34,7 +34,7 @@ or via a configuration file: ## Auto-join with Network Segments -In order to use cloud auto-join with [Network Segments](/docs/enterprise/network-segments), +In order to use cloud auto-join with [Network Segments](/consul/docs/enterprise/network-segments), you must reconfigure the Consul agent's Serf LAN port to match that of the segment you wish to join. @@ -68,7 +68,7 @@ to use port `8303` as its Serf LAN port prior to attempting to join the cluster. The following example configuration overrides the default Serf LAN port using the -[`ports.serf_lan`](/docs/agent/config/config-files#serf_lan_port) configuration option. +[`ports.serf_lan`](/consul/docs/agent/config/config-files#serf_lan_port) configuration option. @@ -84,7 +84,7 @@ ports { The following example overrides the default Serf LAN port using the -[`-serf-lan-port`](/docs/agent/config/cli-flags#_serf_lan_port) command line flag. +[`-serf-lan-port`](/consul/docs/agent/config/cli-flags#_serf_lan_port) command line flag. ```shell $ consul agent -serf-lan-port=8303 -retry-join "provider=..." diff --git a/website/content/docs/install/glossary.mdx b/website/content/docs/install/glossary.mdx index bdcba9b95c..f11ae21e7b 100644 --- a/website/content/docs/install/glossary.mdx +++ b/website/content/docs/install/glossary.mdx @@ -47,14 +47,14 @@ transactions are applied to a [finite-state machine](https://en.wikipedia.org/wiki/Finite-state_machine), our definition of consensus implies the consistency of a replicated state machine. Consensus is described in more detail on [Wikipedia](), -and our implementation is described [here](/docs/architecture/consensus). +and our implementation is described [here](/consul/docs/architecture/consensus). ## Gossip Consul is built on top of [Serf](https://www.serf.io/) which provides a full [gossip protocol](https://en.wikipedia.org/wiki/Gossip_protocol) that is used for multiple purposes. Serf provides membership, failure detection, and event broadcast. Our use of these -is described more in the [gossip documentation](/docs/architecture/gossip). It is enough to know +is described more in the [gossip documentation](/consul/docs/architecture/gossip). It is enough to know that gossip involves random node-to-node communication, primarily over UDP. ## LAN Gossip @@ -84,7 +84,7 @@ operations they can perform. Consul uses Access Control Lists (ACLs) to secure the UI, API, CLI, service communications, and agent communications. -Visit [Consul ACL Documentation and Guides](/docs/security/acl) +Visit [Consul ACL Documentation and Guides](/consul/docs/security/acl) ## API Gateway An Application Programming Interface (API) is a common software interface that diff --git a/website/content/docs/install/index.mdx b/website/content/docs/install/index.mdx index 905e6c25dd..a1ac4ea8b4 100644 --- a/website/content/docs/install/index.mdx +++ b/website/content/docs/install/index.mdx @@ -13,17 +13,17 @@ Installing Consul is simple. There are three approaches to installing Consul: 1. Installing [from source](#compiling-from-source) -1. Installing [on Kubernetes](/docs/k8s/installation/install) +1. Installing [on Kubernetes](/consul/docs/k8s/installation/install) Downloading a precompiled binary is easiest, and we provide downloads over TLS along with SHA256 sums to verify the binary. We also distribute a PGP signature with the SHA256 sums that can be verified. -The [Get Started on VMs tutorials](https://developer.hashicorp.com/consul/tutorials/get-started-vms?utm_source=docs) provide a quick walkthrough of installing and using Consul on a VM. +The [Get Started on VMs tutorials](/consul/tutorials/get-started-vms?utm_source=docs) provide a quick walkthrough of installing and using Consul on a VM. ## Precompiled Binaries -To install the precompiled binary, [download](/downloads) the appropriate +To install the precompiled binary, [download](/consul/downloads) the appropriate package for your system. Consul is currently packaged as a zip file. We do not have any near term plans to provide system packages. @@ -102,4 +102,4 @@ $ consul version Consul currently supports all 'evergreen' browsers, as they are generally on up-to-date versions. For more information on supported browsers, please see our -[FAQ](/docs/troubleshoot/faq) +[FAQ](/consul/docs/troubleshoot/faq) diff --git a/website/content/docs/install/manual-bootstrap.mdx b/website/content/docs/install/manual-bootstrap.mdx index bc297df0ef..99cfbf7195 100644 --- a/website/content/docs/install/manual-bootstrap.mdx +++ b/website/content/docs/install/manual-bootstrap.mdx @@ -9,18 +9,18 @@ description: >- When deploying Consul to a datacenter for the first time, there is an initial bootstrapping that must be done. As of Consul 0.4, an -[automatic bootstrapping](/docs/install/bootstrapping) is available and is +[automatic bootstrapping](/consul/docs/install/bootstrapping) is available and is the recommended approach. However, older versions only support a manual bootstrap that is documented here. Generally, the first nodes that are started are the server nodes. Remember that an agent can run in both client and server mode. Server nodes are responsible -for running the [consensus protocol](/docs/architecture/consensus), and +for running the [consensus protocol](/consul/docs/architecture/consensus), and storing the cluster state. The client nodes are mostly stateless and rely on the server nodes, so they can be started easily. Manual bootstrapping requires that the first server that is deployed in a new -datacenter provide the [`-bootstrap` configuration option](/docs/agent/config/cli-flags#_bootstrap). +datacenter provide the [`-bootstrap` configuration option](/consul/docs/agent/config/cli-flags#_bootstrap). This option allows the server to assert leadership of the cluster without agreement from any other server. This is necessary because at this point, there are no other servers running in @@ -32,7 +32,7 @@ something like the following will be logged: ``` Once `Node A` is running, we can start the next set of servers. There is a -[deployment table](/docs/architecture/consensus#deployment_table) that covers various +[deployment table](/consul/docs/architecture/consensus#deployment_table) that covers various options, but it is recommended to have 3 or 5 total servers per datacenter. A single server deployment is _**highly**_ discouraged as data loss is inevitable in a failure scenario. We start the next servers **without** specifying diff --git a/website/content/docs/install/performance.mdx b/website/content/docs/install/performance.mdx index 8250f7914a..7ab46b2d36 100644 --- a/website/content/docs/install/performance.mdx +++ b/website/content/docs/install/performance.mdx @@ -7,7 +7,7 @@ description: >- # Server Performance -Since Consul servers run a [consensus protocol](/docs/architecture/consensus) to +Since Consul servers run a [consensus protocol](/consul/docs/architecture/consensus) to process all write operations and are contacted on nearly all read operations, server performance is critical for overall throughput and health of a Consul cluster. Servers are generally I/O bound for writes because the underlying Raft log store performs a sync @@ -16,7 +16,7 @@ reads work from a fully in-memory data store that is optimized for concurrent ac ## Minimum Server Requirements ((#minimum)) -In Consul 0.7, the default server [performance parameters](/docs/agent/config/config-files#performance) +In Consul 0.7, the default server [performance parameters](/consul/docs/agent/config/config-files#performance) were tuned to allow Consul to run reliably (but relatively slowly) on a server cluster of three [AWS t2.micro](https://aws.amazon.com/ec2/instance-types/) instances. These thresholds were determined empirically using a leader instance that was under sufficient read, write, @@ -41,7 +41,7 @@ The default performance configuration is equivalent to this: ## Production Server Requirements ((#production)) When running Consul 0.7 and later in production, it is recommended to configure the server -[performance parameters](/docs/agent/config/config-files#performance) back to Consul's original +[performance parameters](/consul/docs/agent/config/config-files#performance) back to Consul's original high-performance settings. This will let Consul servers detect a failed leader and complete leader elections much more quickly than the default configuration which extends key Raft timeouts by a factor of 5, so it can be quite slow during these events. @@ -101,25 +101,25 @@ Here are some general recommendations: issues between the servers or insufficient CPU resources. Users in cloud environments often bump their servers up to the next instance class with improved networking and CPU until leader elections stabilize, and in Consul 0.7 or later the [performance - parameters](/docs/agent/config/config-files#performance) configuration now gives you tools + parameters](/consul/docs/agent/config/config-files#performance) configuration now gives you tools to trade off performance instead of upsizing servers. You can use the [`consul.raft.leader.lastContact` - telemetry](/docs/agent/telemetry#leadership-changes) to observe how the Raft timing is + telemetry](/consul/docs/agent/telemetry#leadership-changes) to observe how the Raft timing is performing and guide the decision to de-tune Raft performance or add more powerful servers. - For DNS-heavy workloads, configuring all Consul agents in a cluster with the - [`allow_stale`](/docs/agent/config/config-files#allow_stale) configuration option will allow reads to + [`allow_stale`](/consul/docs/agent/config/config-files#allow_stale) configuration option will allow reads to scale across all Consul servers, not just the leader. Consul 0.7 and later enables stale reads - for DNS by default. See [Stale Reads](https://learn.hashicorp.com/tutorials/consul/dns-caching#stale-reads) in the - [DNS Caching](https://learn.hashicorp.com/tutorials/consul/dns-caching) guide for more details. It's also good to set - reasonable, non-zero [DNS TTL values](https://learn.hashicorp.com/tutorials/consul/dns-caching#ttl-values) if your clients will + for DNS by default. See [Stale Reads](/consul/tutorials/networking/dns-caching#stale-reads) in the + [DNS Caching](/consul/tutorials/networking/dns-caching) guide for more details. It's also good to set + reasonable, non-zero [DNS TTL values](/consul/tutorials/networking/dns-caching#ttl-values) if your clients will respect them. - In other applications that perform high volumes of reads against Consul, consider using the - [stale consistency mode](/api-docs/features/consistency#stale) available to allow reads to scale + [stale consistency mode](/consul/api-docs/features/consistency#stale) available to allow reads to scale across all the servers and not just be forwarded to the leader. -- In Consul 0.9.3 and later, a new [`limits`](/docs/agent/config/config-files#limits) configuration is +- In Consul 0.9.3 and later, a new [`limits`](/consul/docs/agent/config/config-files#limits) configuration is available on Consul clients to limit the RPC request rate they are allowed to make against the Consul servers. After hitting the limit, requests will start to return rate limit errors until time has passed and more requests are allowed. Configuring this across the cluster can help with @@ -136,7 +136,7 @@ of a snapshot and log of changes since the previous snapshot for durability. When planning for memory requirements, you should typically allocate enough RAM for your server agents to contain between 2 to 4 times the working set size. You can determine the working set size by noting the value of -`consul.runtime.alloc_bytes` in the [Telemetry data](/docs/agent/telemetry). +`consul.runtime.alloc_bytes` in the [Telemetry data](/consul/docs/agent/telemetry). > NOTE: Consul is not designed to serve as a general purpose database, and you > should keep this in mind when choosing what data are populated to the @@ -154,27 +154,27 @@ For **write-heavy** workloads, the total RAM available for overhead must approxi RAM NEEDED = number of keys * average key size * 2-3x ``` -Since writes must be synced to disk (persistent storage) on a quorum of servers before they are committed, deploying a disk with high write throughput (or an SSD) will enhance performance on the write side. ([Documentation](/docs/agent/config/cli-flags#_data_dir)) +Since writes must be synced to disk (persistent storage) on a quorum of servers before they are committed, deploying a disk with high write throughput (or an SSD) will enhance performance on the write side. ([Documentation](/consul/docs/agent/config/cli-flags#_data_dir)) -For a **read-heavy** workload, configure all Consul server agents with the `allow_stale` DNS option, or query the API with the `stale` [consistency mode](/api-docs/features/consistency). By default, all queries made to the server are RPC forwarded to and serviced by the leader. By enabling stale reads, any server will respond to any query, thereby reducing overhead on the leader. Typically, the stale response is `100ms` or less from consistent mode but it drastically improves performance and reduces latency under high load. +For a **read-heavy** workload, configure all Consul server agents with the `allow_stale` DNS option, or query the API with the `stale` [consistency mode](/consul/api-docs/features/consistency). By default, all queries made to the server are RPC forwarded to and serviced by the leader. By enabling stale reads, any server will respond to any query, thereby reducing overhead on the leader. Typically, the stale response is `100ms` or less from consistent mode but it drastically improves performance and reduces latency under high load. -If the leader server is out of memory or the disk is full, the server eventually stops responding, loses its election and cannot move past its last commit time. However, by configuring `max_stale` and setting it to a large value, Consul will continue to respond to queries during such outage scenarios. ([max_stale documentation](/docs/agent/config/config-files#max_stale)). +If the leader server is out of memory or the disk is full, the server eventually stops responding, loses its election and cannot move past its last commit time. However, by configuring `max_stale` and setting it to a large value, Consul will continue to respond to queries during such outage scenarios. ([max_stale documentation](/consul/docs/agent/config/config-files#max_stale)). It should be noted that `stale` is not appropriate for coordination where strong consistency is important (i.e. locking or application leader election). For critical cases, the optional `consistent` API query mode is required for true linearizability; the trade off is that this turns a read into a full quorum write so requires more resources and takes longer. -**Read-heavy** clusters may take advantage of the [enhanced reading](/docs/enterprise/read-scale) feature (Enterprise) for better scalability. This feature allows additional servers to be introduced as non-voters. Being a non-voter, the server will still participate in data replication, but it will not block the leader from committing log entries. +**Read-heavy** clusters may take advantage of the [enhanced reading](/consul/docs/enterprise/read-scale) feature (Enterprise) for better scalability. This feature allows additional servers to be introduced as non-voters. Being a non-voter, the server will still participate in data replication, but it will not block the leader from committing log entries. Consul's agents use network sockets for communicating with the other nodes (gossip) and with the server agent. In addition, file descriptors are also opened for watch handlers, health checks, and log files. For a **write heavy** cluster, the `ulimit` size must be increased from the default value (`1024`) to prevent the leader from running out of file descriptors. -To prevent any CPU spikes from a misconfigured client, RPC requests to the server should be [rate limited](/docs/agent/config/config-files#limits) +To prevent any CPU spikes from a misconfigured client, RPC requests to the server should be [rate limited](/consul/docs/agent/config/config-files#limits) ~> **NOTE** Rate limiting is configured on the client agent only. -In addition, two [performance indicators](/docs/agent/telemetry) — `consul.runtime.alloc_bytes` and `consul.runtime.heap_objects` — can help diagnose if the current sizing is not adequately meeting the load. +In addition, two [performance indicators](/consul/docs/agent/telemetry) — `consul.runtime.alloc_bytes` and `consul.runtime.heap_objects` — can help diagnose if the current sizing is not adequately meeting the load. ## Connect Certificate Signing CPU Limits -If you enable [Connect](/docs/connect), the leader server will need +If you enable [Connect](/consul/docs/connect), the leader server will need to perform public key signing operations for every service instance in the cluster. Typically these operations are fast on modern hardware, however when the CA is changed or its key rotated, the leader will face an influx of @@ -189,8 +189,8 @@ Smearing requests over 30s is sufficient to bring RPC load to a reasonable level in all but the very largest clusters, but the extra CPU load from cryptographic operations could impact the server's normal work. To limit that, Consul since 1.4.1 exposes two ways to limit the impact Certificate signing has on the leader -[`csr_max_per_second`](/docs/agent/config/config-files#ca_csr_max_per_second) and -[`csr_max_concurrent`](/docs/agent/config/config-files#ca_csr_max_concurrent). +[`csr_max_per_second`](/consul/docs/agent/config/config-files#ca_csr_max_per_second) and +[`csr_max_concurrent`](/consul/docs/agent/config/config-files#ca_csr_max_concurrent). By default we set a limit of 50 per second which is reasonable on modest hardware but may be too low and impact rotation times if more than 1500 service diff --git a/website/content/docs/install/ports.mdx b/website/content/docs/install/ports.mdx index f40e1756ad..0e53d91899 100644 --- a/website/content/docs/install/ports.mdx +++ b/website/content/docs/install/ports.mdx @@ -54,4 +54,4 @@ the Serf WAN port (TCP/UDP) to be listening on both WAN and LAN interfaces. See **Server RPC** This is used by servers to handle incoming requests from other agents. -Note, the default ports can be changed in the [agent configuration](/docs/agent/config/config-files#ports). +Note, the default ports can be changed in the [agent configuration](/consul/docs/agent/config/config-files#ports). diff --git a/website/content/docs/integrate/download-tools.mdx b/website/content/docs/integrate/download-tools.mdx index 4953f5f56e..a1263b7d81 100644 --- a/website/content/docs/integrate/download-tools.mdx +++ b/website/content/docs/integrate/download-tools.mdx @@ -15,13 +15,13 @@ These Consul tools are created and managed by the dedicated engineers at HashiCo - [Envconsul](https://github.com/hashicorp/envconsul) - Read and set environmental variables for processes from Consul. - [Consul API Gateway](https://github.com/hashicorp/consul-api-gateway/) - dedicated ingress solution for intelligently routing traffic to applications running on a Consul Service Mesh. -- [Consul ESM](https://github.com/hashicorp/consul-esm) - Provides external service monitoring for Consul. Complete the [tutorial]((https://learn.hashicorp.com/tutorials/consul/service-registration-external-services?utm_source=docs)) to learn more. +- [Consul ESM](https://github.com/hashicorp/consul-esm) - Provides external service monitoring for Consul. Complete the [tutorial](https://consul.io/(https://learn.hashicorp.com/tutorials/consul/service-registration-external-services?utm_source=docs)) to learn more. - [Consul Migrate](https://github.com/hashicorp/consul-migrate) - Data migration tool to handle Consul upgrades to 0.5.1+ - [Consul Replicate](https://github.com/hashicorp/consul-replicate) - Consul cross-DC KV replication daemon. -- [Consul Template](https://github.com/hashicorp/consul-template) - Generic template rendering and notifications with Consul. Complete the [tutorial](https://learn.hashicorp.com/tutorials/consul/consul-template?utm_source=docs) to the learn more. +- [Consul Template](https://github.com/hashicorp/consul-template) - Generic template rendering and notifications with Consul. Complete the [tutorial](/consul/tutorials/developer-configuration/consul-template?utm_source=docs) to the learn more. - [Consul-Terraform Sync](https://github.com/hashicorp/consul-terraform-sync) - enables dynamic updates to network infrastructure devices triggered by service -changes. Complete the [tutorial](https://learn.hashicorp.com/collections/consul/network-infrastructure-automation?utm_source=docs) to learn more. +changes. Complete the [tutorial](/consul/tutorials/network-infrastructure-automation?utm_source=docs) to learn more. ## Community Tools diff --git a/website/content/docs/integrate/nia-integration.mdx b/website/content/docs/integrate/nia-integration.mdx index 03c67da0fb..6c1ff3390c 100644 --- a/website/content/docs/integrate/nia-integration.mdx +++ b/website/content/docs/integrate/nia-integration.mdx @@ -11,13 +11,13 @@ HashiCorp's Network Infrastructure Automation (NIA) Integration Program allows p ## Network Infrastructure Automation -Network Infrastructure Automation (NIA) relies on a declarative, workflow and service driven network automation architecture. NIA is carried out by [`Consul-Terraform-Sync`](/docs/nia) which leverages Terraform as the underlying automation tool and utilizes the Terraform provider ecosystem to drive relevant change to the network infrastructure. This usage of the Terraform provider in conjunction with Consul-Terraform-Sync allows for HashiCorp Consul to act as the core data source where it is updated with the state of the infrastructure. +Network Infrastructure Automation (NIA) relies on a declarative, workflow and service driven network automation architecture. NIA is carried out by [`Consul-Terraform-Sync`](/consul/docs/nia) which leverages Terraform as the underlying automation tool and utilizes the Terraform provider ecosystem to drive relevant change to the network infrastructure. This usage of the Terraform provider in conjunction with Consul-Terraform-Sync allows for HashiCorp Consul to act as the core data source where it is updated with the state of the infrastructure. Consul-Terraform-Sync executes one or more automation tasks with an appropriate value of service variables based on updates from the Consul service catalog. Each task consists of a runbook automation written as a compatible Terraform module using resources and data sources for the underlying network infrastructure. The Consul-Terraform-Sync daemon runs on the same node as a Consul agent. [![NIA Architecture](/img/nia-highlevel-diagram.svg)](/img/nia-highlevel-diagram.svg) --> Please note that the above indicated solution is a “push” based method and is not the only way to integrate network devices with Consul and drive Network Infrastructure Automation Integration. If your preferred method is to directly integrate with Consul without using Terraform, then please use [Consul Integration Program](/docs/integrate/partnerships). +-> Please note that the above indicated solution is a “push” based method and is not the only way to integrate network devices with Consul and drive Network Infrastructure Automation Integration. If your preferred method is to directly integrate with Consul without using Terraform, then please use [Consul Integration Program](/consul/docs/integrate/partnerships). ## NIA Program Steps @@ -42,16 +42,16 @@ Please begin by providing the following details: [NIA Integration Program](https Consul-Terraform-Sync compatible Terraform module development process is fairly straightforward and simple when technology partners have experience with building Terraform configuration files. Adopting Terraform best practices helps expedite the review and release cycles. -- Consul [documentation](/docs) -- Consul-Terraform-Sync [documentation](/docs/nia) -- Writing Consul-Terraform-Sync compatible Terraform modules using our [guide](/docs/nia/terraform-modules) and [tutorial](https://learn.hashicorp.com/tutorials/consul/consul-terraform-sync-module?utm_source=docs) +- Consul [documentation](/consul/docs) +- Consul-Terraform-Sync [documentation](/consul/docs/nia) +- Writing Consul-Terraform-Sync compatible Terraform modules using our [guide](/consul/docs/nia/terraform-modules) and [tutorial](/consul/tutorials/network-infrastructure-automation/consul-terraform-sync-module?utm_source=docs) - Example Terraform Modules for reference: [PAN-OS](https://registry.terraform.io/modules/PaloAltoNetworks/dag-nia/panos/latest), [Simple Print Module](https://registry.terraform.io/modules/findkim/print/cts/latest) and a [Template to structure your Terraform Modules](https://github.com/hashicorp/consul-terraform-sync-template-module) -- Publishing to the Terraform Registry [guidelines](https://www.terraform.io/registry/modules/publish) +- Publishing to the Terraform Registry [guidelines](/terraform/registry/modules/publish) ### 3. Develop & Test -Terraform modules are written in HashiCorp Configuration Language (HCL). Writing [Terraform modules](https://www.terraform.io/language/modules/develop) or a [tutorial to build a module](https://learn.hashicorp.com/tutorials/terraform/module-create) are good resources to begin writing a new module. -Consul-Terraform-Sync compatible modules follow the [standard module structure](https://www.terraform.io/language/modules/develop). Modules can use syntax supported by Terraform version 0.13, or higher. Consul-Terraform-Sync is designed to integrate with any module that satisfies these [specifications](/docs/nia/terraform-modules#module-specifications). The guide will give you an introduction of the code structure and the basics of authoring a plugin that Terraform can interact with. +Terraform modules are written in HashiCorp Configuration Language (HCL). Writing [Terraform modules](/terraform/language/modules/develop) or a [tutorial to build a module](/terraform/tutorials/modules/module-create) are good resources to begin writing a new module. +Consul-Terraform-Sync compatible modules follow the [standard module structure](/terraform/language/modules/develop). Modules can use syntax supported by Terraform version 0.13, or higher. Consul-Terraform-Sync is designed to integrate with any module that satisfies these [specifications](/consul/docs/nia/terraform-modules#module-specifications). The guide will give you an introduction of the code structure and the basics of authoring a plugin that Terraform can interact with. It is recommended that partners develop modules that cater to specific workflows on an individual platform in their product portfolio rather than having overarching modules that try to cover multiple workflows across different platforms. This is to keep the automation modular and adoptable by a broad set of users with varying network infrastructure topologies. Partners are encouraged to test the functionality of the modules against their supported platforms. @@ -87,7 +87,7 @@ Once the module development has been completed another email should be sent to n At this stage, it is expected that the module is fully developed, all tests and documentation are in place, and that HashiCorp has reviewed the module to be compatible with Consul-Terraform-Sync. -Once this is done, HashiCorp will get the new module listed as Consul-Terraform-Sync compatible on [consul.io](/docs/nia/usage/requirements#partner-terraform-modules), and then the partner will be asked to publish the Terraform module to the [Terraform Registry](https://registry.terraform.io/browse/modules). +Once this is done, HashiCorp will get the new module listed as Consul-Terraform-Sync compatible on [consul.io](/consul/docs/nia/usage/requirements#partner-terraform-modules), and then the partner will be asked to publish the Terraform module to the [Terraform Registry](https://registry.terraform.io/browse/modules). ### 6. Support @@ -95,7 +95,7 @@ Many partners view the release step to be the end of the journey, while at Hashi The expectation is to resolve all critical issues within 48 hours and all other issues within 5 business days. HashiCorp Consul and Terraform have an extremely wide community of users and contributors and we encourage everyone to report issues however small, as well as help resolve them when possible. -Partners who choose to not follow the process of NIA Integration Program for their Consul-Terraform-Sync compatible Terraform modules will not have their modules listed on [consul.io](/docs/nia/usage/requirements#partner-terraform-modules). +Partners who choose to not follow the process of NIA Integration Program for their Consul-Terraform-Sync compatible Terraform modules will not have their modules listed on [consul.io](/consul/docs/nia/usage/requirements#partner-terraform-modules). ### Contact Us diff --git a/website/content/docs/integrate/partnerships.mdx b/website/content/docs/integrate/partnerships.mdx index be601d0570..0f9f7301b7 100644 --- a/website/content/docs/integrate/partnerships.mdx +++ b/website/content/docs/integrate/partnerships.mdx @@ -35,11 +35,11 @@ By leveraging Consul's RESTful HTTP API system, prospective partners are able to **Infrastructure**: There are two integration options in this category: natively through a direct integration with Consul or via Consul-Terraform-Sync (CTS). By leveraging Consul's powerful **Network Infrastructure Automation (NIA)*** capabilities through CTS, changes in an infrastructure are seamlessly automated when Consul detects a change in its service catalog. For example, these integrations could be used to automate IP updates of load balancers or firewall security policies by leveraging Consul service discovery. --> **Network Infrastructure Automation (NIA)***: These integrations leverage Consul's service catalog to seamlessly integrate with Consul-Terraform-Sync (CTS) to automate changes in network infrastructure via a publisher-subscriber method. Refer to the [NIA documentation](/docs/integrate/nia-integration) for details. +-> **Network Infrastructure Automation (NIA)***: These integrations leverage Consul's service catalog to seamlessly integrate with Consul-Terraform-Sync (CTS) to automate changes in network infrastructure via a publisher-subscriber method. Refer to the [NIA documentation](/consul/docs/integrate/nia-integration) for details. **HCP Consul**: HCP Consul is secure by default and offers an out-of-the-box service mesh solution to streamline operations without the hassle of managing Consul servers. [Sign up for a free HCP Consul account](https://cloud.hashicorp.com/products/consul). -**Consul integration verification badges**: Partners will be issued the Consul Enterprise badge for integrations that work with [Consul Enterprise features](https://www.consul.io/docs/enterprise) such as namespaces. Partners will be issued the HCP Consul badge for integrations validated to work with [HCP Consul](https://cloud.hashicorp.com/docs/consul#features). Each badge would be displayed on HashiCorp's partner page as well as be available for posting on the partner's own website to provide better visibility and differentiation of the integration for joint customers. +**Consul integration verification badges**: Partners will be issued the Consul Enterprise badge for integrations that work with [Consul Enterprise features](/consul/docs/enterprise) such as namespaces. Partners will be issued the HCP Consul badge for integrations validated to work with [HCP Consul](/hcp/docs/consul#features). Each badge would be displayed on HashiCorp's partner page as well as be available for posting on the partner's own website to provide better visibility and differentiation of the integration for joint customers. @@ -85,7 +85,7 @@ Here are links to resources, documentation, examples and best practices to guide **Application Performance Monitoring (APM)** -- [Consul Telemetry Documentation](/docs/agent/telemetry) +- [Consul Telemetry Documentation](/consul/docs/agent/telemetry) - [Monitoring Consul with Datadog APM](https://www.datadoghq.com/blog/consul-datadog/) - [Monitor HCP Consul with New Relic Instant Observability](https://github.com/newrelic-experimental/hashicorp-quickstart-annex/blob/main/hcp-consul/README.md) - [HCP Consul and CloudFabrix AIOps Integration](https://bot-docs.cloudfabrix.io/Bots/consul/?h=consul) @@ -112,15 +112,15 @@ Here are links to resources, documentation, examples and best practices to guide - [F5 Terminating Gateway Integration Documentation](https://www.hashicorp.com/integrations/f5-networks/consul) - [Traefik Integration with Consul Service Mesh](https://traefik.io/blog/integrating-consul-connect-service-mesh-with-traefik-2-5/) - [Kong's Ingress Controller Integration with Consul](https://www.hashicorp.com/integrations/kong/consul) -- [Configuring Ingress Controllers with Consul-on-Kubernetes](https://www.consul.io/docs/k8s/connect/ingress-controllers) -- [Introduction to Consul Transparent Proxy](https://www.consul.io/docs/connect/transparent-proxy) +- [Configuring Ingress Controllers with Consul-on-Kubernetes](/consul/docs/k8s/connect/ingress-controllers) +- [Introduction to Consul Transparent Proxy](/consul/docs/connect/transparent-proxy) - [Getting Started with Transparent Proxy](https://www.hashicorp.com/blog/transparent-proxy-on-consul-service-mesh) #### Platform: -- [Deploy Consul on Red Hat OpenShift](https://learn.hashicorp.com/tutorials/consul/kubernetes-openshift-red-hat) +- [Deploy Consul on Red Hat OpenShift](/consul/tutorials/kubernetes/kubernetes-openshift-red-hat) - [Consul Integration with Layer5 Meshery](https://www.hashicorp.com/integrations/layer5-io/consul) -- [Consul Integration with VMware Tanzu Application Service](https://learn.hashicorp.com/tutorials/consul/sync-pivotal-cloud-services?utm_source=docs) +- [Consul Integration with VMware Tanzu Application Service](/consul/tutorials/cloud-integrations/sync-pivotal-cloud-services?utm_source=docs) #### Infrastructure: @@ -141,8 +141,8 @@ Here are links to resources, documentation, examples and best practices to guide **Load Balancer** -- [Load Balancing with NGINX and Consul Template](https://learn.hashicorp.com/tutorials/consul/load-balancing-nginx?utm_source=docs) -- [Load Balancing with HAProxy Service Discovery](https://learn.hashicorp.com/tutorials/consul/load-balancing-haproxy?utm_source=docs) +- [Load Balancing with NGINX and Consul Template](/consul/tutorials/load-balancing/load-balancing-nginx?utm_source=docs) +- [Load Balancing with HAProxy Service Discovery](/consul/tutorials/load-balancing/load-balancing-haproxy?utm_source=docs) **Network Infrastructure Automation:** @@ -151,7 +151,7 @@ Here are links to resources, documentation, examples and best practices to guide **Application Delivery Controllers \(ADC\)** -- [Automate A10 ADC with Consul NIA](https://learn.hashicorp.com/tutorials/consul/consul-terraform-sync-a10-adc?utm_source=docs) +- [Automate A10 ADC with Consul NIA](/consul/tutorials/network-infrastructure-automation/consul-terraform-sync-a10-adc?utm_source=docs) - [Automate Citrix ADC with Consul NIA](https://www.hashicorp.com/integrations/citrix-adc/consul) **Domain Name Service (DNS) Automation** @@ -174,10 +174,10 @@ HCP Consul is currently only deployed on AWS and Microsoft Azure, so your applic #### HCP Consul Resource Links: - [Getting Started with HCP Consul](/consul/tutorials/get-started-hcp/hcp-gs-deploy) -- [HCP Consul End-to-End Deployment](https://learn.hashicorp.com/tutorials/cloud/consul-end-to-end-overview?in=consul/cloud-deploy-automation) -- [Deploy HCP Consul with EKS using Terraform](https://learn.hashicorp.com/tutorials/cloud/consul-end-to-end-eks?in=consul/cloud-deploy-automation) -- [HCP Consul Deployment Automation](https://learn.hashicorp.com/collections/consul/cloud-deploy-automation) -- [HCP Consul documentation](https://cloud.hashicorp.com/docs/consul/usage) +- [HCP Consul End-to-End Deployment](/consul/tutorials/cloud-deploy-automation/consul-end-to-end-overview) +- [Deploy HCP Consul with EKS using Terraform](/consul/tutorials/cloud-deploy-automation/consul-end-to-end-eks) +- [HCP Consul Deployment Automation](/consul/tutorials/cloud-deploy-automation) +- [HCP Consul documentation](/hcp/docs/consul/usage) **Consul Enterprise**: An integration qualifies for Consul Enterprise when it is tested and compatible with Consul Enterprise Namespaces. diff --git a/website/content/docs/internals/acl.mdx b/website/content/docs/internals/acl.mdx index 391ee45031..05c8d38019 100644 --- a/website/content/docs/internals/acl.mdx +++ b/website/content/docs/internals/acl.mdx @@ -10,7 +10,7 @@ description: >- # ACL System ((#version_8_acls)) -This content has been moved into the [ACL Guide](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production). +This content has been moved into the [ACL Guide](/consul/tutorials/security/access-control-setup-production). -See [Complete ACL Coverage in Consul 0.8](/docs/security/acl/acl-legacy) for details +See [Complete ACL Coverage in Consul 0.8](/consul/docs/security/acl/acl-legacy) for details about ACL changes in Consul 0.8 and later. diff --git a/website/content/docs/internals/index.mdx b/website/content/docs/internals/index.mdx index ae82e5e035..20b3c80571 100644 --- a/website/content/docs/internals/index.mdx +++ b/website/content/docs/internals/index.mdx @@ -12,14 +12,14 @@ use it in production. Please review the following documentation to understand how Consul works. -- [Architecture](/docs/architecture) -- [Consensus Protocol](/docs/architecture/consensus) -- [Gossip Protocol](/docs/architecture/gossip) -- [Network Coordinates](/docs/architecture/coordinates) -- [Sessions](/docs/security/acl/auth-methods/oidc) -- [Anti-Entropy](/docs/architecture/anti-entropy) -- [Security Model](/docs/security) -- [Discovery Chain](/docs/connect/l7-traffic/discovery-chain) +- [Architecture](/consul/docs/architecture) +- [Consensus Protocol](/consul/docs/architecture/consensus) +- [Gossip Protocol](/consul/docs/architecture/gossip) +- [Network Coordinates](/consul/docs/architecture/coordinates) +- [Sessions](/consul/docs/security/acl/auth-methods/oidc) +- [Anti-Entropy](/consul/docs/architecture/anti-entropy) +- [Security Model](/consul/docs/security) +- [Discovery Chain](/consul/docs/connect/l7-traffic/discovery-chain) -You should also be familiar with [Jepsen testing](/docs/architecture/jepsen), before deploying +You should also be familiar with [Jepsen testing](/consul/docs/architecture/jepsen), before deploying a production datacenter. diff --git a/website/content/docs/intro/index.mdx b/website/content/docs/intro/index.mdx index 89d4f67a88..50834137b4 100644 --- a/website/content/docs/intro/index.mdx +++ b/website/content/docs/intro/index.mdx @@ -10,21 +10,21 @@ description: >- HashiCorp Consul is a service networking solution that enables teams to manage secure network connectivity between services and across on-prem and multi-cloud environments and runtimes. Consul offers service discovery, service mesh, traffic management, and automated updates to network infrastructure device. You can use these features individually or together in a single Consul deployment. > **Hands-on**: Complete the Getting Started tutorials to learn how to deploy Consul: -- [Get Started on Kubernetes](https://learn.hashicorp.com/collections/consul/gs-consul-service-mesh) -- [Get Started on VMs](https://learn.hashicorp.com/collections/consul/getting-started) -- [HashiCorp Cloud Platform (HCP) Consul](https://learn.hashicorp.com/collections/consul/cloud-get-started) +- [Get Started on Kubernetes](/consul/tutorials/gs-consul-service-mesh) +- [Get Started on VMs](/consul/tutorials/getting-started) +- [HashiCorp Cloud Platform (HCP) Consul](/consul/tutorials/cloud-get-started) ## How does Consul work? Consul provides a _control plane_ that enables you to register, query, and secure services deployed across your network. The control plane is the part of the network infrastructure that maintains a central registry to track services and their respective IP addresses. It is a distributed system that runs on clusters of nodes, such as physical servers, cloud instances, virtual machines, or containers. -Consul interacts with the _data plane_ through proxies. The data plane is the part of the network infrastructure that processes data requests. Refer to [Consul Architecture](/docs/architecture) for details. +Consul interacts with the _data plane_ through proxies. The data plane is the part of the network infrastructure that processes data requests. Refer to [Consul Architecture](/consul/docs/architecture) for details. ![Basic Consul workflow](/img/what-is-consul-overview-diagram.png) The core Consul workflow consists of the following stages: -- **Register**: Teams add services to the Consul catalog, which is a central registry that lets services automatically discover each other without requiring a human operator to modify application code, deploy additional load balancers, or hardcode IP addresses. It is the runtime source of truth for all services and their addresses. Teams can manually [define and register services](/docs/discovery/services) using the CLI or the API, or you can automate the process in Kubernetes with [service sync](/docs/k8s/service-sync). Services can also include health checks so that Consul can monitor for unhealthy services. +- **Register**: Teams add services to the Consul catalog, which is a central registry that lets services automatically discover each other without requiring a human operator to modify application code, deploy additional load balancers, or hardcode IP addresses. It is the runtime source of truth for all services and their addresses. Teams can manually [define and register services](/consul/docs/discovery/services) using the CLI or the API, or you can automate the process in Kubernetes with [service sync](/consul/docs/k8s/service-sync). Services can also include health checks so that Consul can monitor for unhealthy services. - **Query**: Consul’s identity-based DNS lets you find healthy services in the Consul catalog. Services registered with Consul provide health information, access points, and other data that help you control the flow of data through your network. Your services only access other services through their local proxy according to the identity-based policies you define. - **Secure**: After services locate upstreams, Consul ensures that service-to-service communication is authenticated, authorized, and encrypted. Consul service mesh secures microservice architectures with mTLS and can allow or restrict access based on service identities, regardless of differences in compute environments and runtimes. @@ -57,7 +57,7 @@ You can also schedule Consul workloads with [HashiCorp Nomad](https://www.nomadp Microservice architectures are complex and difficult to secure against accidental discloser to malicious actors. Consul provides several mechanisms that enhance network security without any changes to your application code, including mutual transport layer security (mTLS) encryption on all traffic between services and Consul intentions, which are service-to-service permissions that you can manage through the Consul UI, API, and CLI. -When you deploy Consul to Kubernetes clusters, you can also integrate with [HashiCorp Vault](https://www.vaultproject.io/) to manage sensitive data. By default, Consul on Kubernetes leverages Kubernetes secrets as the backend system. Kubernetes secrets are base64 encoded, unencrypted, and lack lease or time-to-live properties. By leveraging Vault as a secrets backend for Consul on Kubernetes, you can manage and store Consul related secrets within a centralized Vault cluster to use across one or many Consul on Kubernetes datacenters. Refer to [Vault as the Secrets Backend](/docs/k8s/deployment-configurations/vault) for additional information. +When you deploy Consul to Kubernetes clusters, you can also integrate with [HashiCorp Vault](https://www.vaultproject.io/) to manage sensitive data. By default, Consul on Kubernetes leverages Kubernetes secrets as the backend system. Kubernetes secrets are base64 encoded, unencrypted, and lack lease or time-to-live properties. By leveraging Vault as a secrets backend for Consul on Kubernetes, you can manage and store Consul related secrets within a centralized Vault cluster to use across one or many Consul on Kubernetes datacenters. Refer to [Vault as the Secrets Backend](/consul/docs/k8s/deployment-configurations/vault) for additional information. You can also secure your Consul deployment, itself, by defining security policies in access control lists (ACL) to control access to data and Consul APIs. diff --git a/website/content/docs/k8s/annotations-and-labels.mdx b/website/content/docs/k8s/annotations-and-labels.mdx index 63b407fb15..7e47262442 100644 --- a/website/content/docs/k8s/annotations-and-labels.mdx +++ b/website/content/docs/k8s/annotations-and-labels.mdx @@ -71,7 +71,7 @@ The following Kubernetes resource annotations could be used on a pod to control - Unlabeled: Use the unlabeled annotation format to specify a service name, Consul Enterprise namespaces and partitions, and - datacenters. To use [cluster peering](/docs/connect/cluster-peering/k8s) with upstreams, use the following + datacenters. To use [cluster peering](/consul/docs/connect/cluster-peering/k8s) with upstreams, use the following labeled format. - Service name: Place the service name at the beginning of the annotation to specify the upstream service. You can also append the datacenter where the service is deployed (optional). @@ -94,12 +94,12 @@ The following Kubernetes resource annotations could be used on a pod to control - Admin partitions (requires Consul Enterprise 1.11+): Upstream services may be running in a different partition. You must specify the namespace when specifying a partition. Place the partition name after the namespace. If you specify the name of the datacenter (optional), it must be the local datacenter. Communicating across partitions using this method is only supported within a datacenter. For cross partition communication across datacenters, refer to [cluster - peering](/docs/connect/cluster-peering/k8s). + peering](/consul/docs/connect/cluster-peering/k8s). ```yaml annotations: "consul.hashicorp.com/connect-service-upstreams":"[service-name].[service-namespace].[service-partition]:[port]:[optional datacenter]" ``` - - [Prepared queries](/api-docs/query): Prepend the annotation + - [Prepared queries](/consul/api-docs/query): Prepend the annotation with `prepared_query` and place the name of the query at the beginning of the string. ```yaml annotations: @@ -196,7 +196,7 @@ The following Kubernetes resource annotations could be used on a pod to control - `consul.hashicorp.com/sidecar-proxy-` - Override default resource settings for the sidecar proxy container. - The defaults are set in Helm config via the [`connectInject.sidecarProxy.resources`](/docs/k8s/helm#v-connectinject-sidecarproxy-resources) key. + The defaults are set in Helm config via the [`connectInject.sidecarProxy.resources`](/consul/docs/k8s/helm#v-connectinject-sidecarproxy-resources) key. - `consul.hashicorp.com/sidecar-proxy-cpu-limit` - Override the default CPU limit. - `consul.hashicorp.com/sidecar-proxy-cpu-request` - Override the default CPU request. @@ -208,18 +208,18 @@ The following Kubernetes resource annotations could be used on a pod to control - `consul.hashicorp.com/consul-sidecar-` - Override default resource settings for the `consul-sidecar` container. - The defaults are set in Helm config via the [`global.consulSidecarContainer.resources`](/docs/k8s/helm#v-global-consulsidecarcontainer) key. + The defaults are set in Helm config via the [`global.consulSidecarContainer.resources`](/consul/docs/k8s/helm#v-global-consulsidecarcontainer) key. - `consul.hashicorp.com/consul-sidecar-cpu-limit` - Override the default CPU limit. - `consul.hashicorp.com/consul-sidecar-cpu-request` - Override the default CPU request. - `consul.hashicorp.com/consul-sidecar-memory-limit` - Override the default memory limit. - `consul.hashicorp.com/consul-sidecar-memory-request` - Override the default memory request. -- `consul.hashicorp.com/enable-metrics` - Override the default Helm value [`connectInject.metrics.defaultEnabled`](/docs/k8s/helm#v-connectinject-metrics-defaultenabled). -- `consul.hashicorp.com/enable-metrics-merging` - Override the default Helm value [`connectInject.metrics.defaultEnableMerging`](/docs/k8s/helm#v-connectinject-metrics-defaultenablemerging). -- `consul.hashicorp.com/merged-metrics-port` - Override the default Helm value [`connectInject.metrics.defaultMergedMetricsPort`](/docs/k8s/helm#v-connectinject-metrics-defaultmergedmetricsport). -- `consul.hashicorp.com/prometheus-scrape-port` - Override the default Helm value [`connectInject.metrics.defaultPrometheusScrapePort`](/docs/k8s/helm#v-connectinject-metrics-defaultprometheusscrapeport). -- `consul.hashicorp.com/prometheus-scrape-path` - Override the default Helm value [`connectInject.metrics.defaultPrometheusScrapePath`](/docs/k8s/helm#v-connectinject-metrics-defaultprometheusscrapepath). +- `consul.hashicorp.com/enable-metrics` - Override the default Helm value [`connectInject.metrics.defaultEnabled`](/consul/docs/k8s/helm#v-connectinject-metrics-defaultenabled). +- `consul.hashicorp.com/enable-metrics-merging` - Override the default Helm value [`connectInject.metrics.defaultEnableMerging`](/consul/docs/k8s/helm#v-connectinject-metrics-defaultenablemerging). +- `consul.hashicorp.com/merged-metrics-port` - Override the default Helm value [`connectInject.metrics.defaultMergedMetricsPort`](/consul/docs/k8s/helm#v-connectinject-metrics-defaultmergedmetricsport). +- `consul.hashicorp.com/prometheus-scrape-port` - Override the default Helm value [`connectInject.metrics.defaultPrometheusScrapePort`](/consul/docs/k8s/helm#v-connectinject-metrics-defaultprometheusscrapeport). +- `consul.hashicorp.com/prometheus-scrape-path` - Override the default Helm value [`connectInject.metrics.defaultPrometheusScrapePath`](/consul/docs/k8s/helm#v-connectinject-metrics-defaultprometheusscrapepath). - `consul.hashicorp.com/prometheus-ca-file` - Local filesystem path to a CA file for Envoy to use when serving TLS on the Prometheus metrics endpoint. Only applicable when `envoy_prometheus_bind_addr` is set in proxy config. diff --git a/website/content/docs/k8s/architecture.mdx b/website/content/docs/k8s/architecture.mdx index 568bd4994c..58526dc3ba 100644 --- a/website/content/docs/k8s/architecture.mdx +++ b/website/content/docs/k8s/architecture.mdx @@ -7,7 +7,7 @@ description: >- # Architecture -This topic describes the architecture, components, and resources associated with Consul deployments to Kubernetes. Consul employs the same architectural design on Kubernetes as it does with other platforms, but Kubernetes provides additional benefits that make operating a Consul cluster easier. Refer to [Consul Architecture](/docs/architecture) for more general information on Consul's architecture. +This topic describes the architecture, components, and resources associated with Consul deployments to Kubernetes. Consul employs the same architectural design on Kubernetes as it does with other platforms, but Kubernetes provides additional benefits that make operating a Consul cluster easier. Refer to [Consul Architecture](/consul/docs/architecture) for more general information on Consul's architecture. > **For more specific guidance:** > - For guidance on datacenter design, refer to [Consul and Kubernetes Reference Architecture](/consul/tutorials/kubernetes-production/kubernetes-reference-architecture). @@ -18,7 +18,7 @@ This topic describes the architecture, components, and resources associated with The server agents are deployed as a `StatefulSet` and use persistent volume claims to store the server state. This also ensures that the -[node ID](/docs/agent/config/config-files#node_id) is persisted so that servers +[node ID](/consul/docs/agent/config/config-files#node_id) is persisted so that servers can be rescheduled onto new IP addresses without causing issues. The server agents are configured with [anti-affinity](https://kubernetes.io/docs/concepts/configuration/assign-pod-node/#affinity-and-anti-affinity) @@ -43,6 +43,6 @@ By default, Consul on Kubernetes uses an alternate service mesh configuration th ![Diagram of Consul Dataplanes in Kubernetes deployment](/img/k8s-dataplanes-architecture.png) -Refer to [Simplified Service Mesh with Consul Dataplanes](/docs/connect/dataplane) for more information. +Refer to [Simplified Service Mesh with Consul Dataplanes](/consul/docs/connect/dataplane) for more information. -Consul Dataplane is the default proxy manager in Consul on Kubernetes 1.14 and later. If you are on Consul 1.13 or older, refer to [upgrading to Consul Dataplane](/docs/k8s/upgrade#upgrading-to-consul-dataplanes) for specific upgrade instructions. +Consul Dataplane is the default proxy manager in Consul on Kubernetes 1.14 and later. If you are on Consul 1.13 or older, refer to [upgrading to Consul Dataplane](/consul/docs/k8s/upgrade#upgrading-to-consul-dataplanes) for specific upgrade instructions. diff --git a/website/content/docs/k8s/compatibility.mdx b/website/content/docs/k8s/compatibility.mdx index d7c5c79aff..60f71bdcb8 100644 --- a/website/content/docs/k8s/compatibility.mdx +++ b/website/content/docs/k8s/compatibility.mdx @@ -21,7 +21,7 @@ Consul Kubernetes versions all of its components (`consul-k8s` CLI, `consul-k8s- ## Supported Envoy versions -Supported versions of Envoy and `consul-dataplane` (for Consul K8s 1.0 and above) for Consul versions are also found in [Envoy - Supported Versions](/docs/connect/proxies/envoy#supported-versions). Starting with `consul-k8s` 1.0, `consul-dataplane` will include a bundled version of Envoy. The recommended best practice is to use the default version of Envoy or `consul-dataplane` that is provided in the Helm `values.yaml` file, as that is the version that has been tested with the default Consul and Consul Kubernetes binaries for a given Helm chart. +Supported versions of Envoy and `consul-dataplane` (for Consul K8s 1.0 and above) for Consul versions are also found in [Envoy - Supported Versions](/consul/docs/connect/proxies/envoy#supported-versions). Starting with `consul-k8s` 1.0, `consul-dataplane` will include a bundled version of Envoy. The recommended best practice is to use the default version of Envoy or `consul-dataplane` that is provided in the Helm `values.yaml` file, as that is the version that has been tested with the default Consul and Consul Kubernetes binaries for a given Helm chart. ## Vault as a Secrets Backend compatibility diff --git a/website/content/docs/k8s/connect/connect-ca-provider.mdx b/website/content/docs/k8s/connect/connect-ca-provider.mdx index 45745a5d44..1699da1dab 100644 --- a/website/content/docs/k8s/connect/connect-ca-provider.mdx +++ b/website/content/docs/k8s/connect/connect-ca-provider.mdx @@ -7,19 +7,19 @@ description: >- # Configure Certificate Authority for Consul on Kubernetes -If `connect` is enabled, the built-in Consul certificate authority (CA) is automatically enabled for the service mesh CA. You can use different CA providers with Consul service mesh. Refer to [Connect Certificate Management](/docs/connect/ca) for supported providers. +If `connect` is enabled, the built-in Consul certificate authority (CA) is automatically enabled for the service mesh CA. You can use different CA providers with Consul service mesh. Refer to [Connect Certificate Management](/consul/docs/connect/ca) for supported providers. ## Overview -You should only complete the following instructions during the initial cluster bootstrapping procedure with Consul K8s CLI 0.38.0 or later. To update the Consul service mesh CA provider on an existing cluster or to update any provider properties, such as tokens, refer to [Update CA Configuration Endpoint](/api-docs/connect/ca#update-ca-configuration). +You should only complete the following instructions during the initial cluster bootstrapping procedure with Consul K8s CLI 0.38.0 or later. To update the Consul service mesh CA provider on an existing cluster or to update any provider properties, such as tokens, refer to [Update CA Configuration Endpoint](/consul/api-docs/connect/ca#update-ca-configuration). To configure an external CA provider using the Consul Helm chart, complete the following steps: 1. Create a configuration file containing your provider information. 1. Create a Kubernetes secret containing the configuration file. -1. Reference the Kubernetes secret in the [`server.extraVolumes`](/docs/k8s/helm#v-server-extravolumes) value in the Helm chart. +1. Reference the Kubernetes secret in the [`server.extraVolumes`](/consul/docs/k8s/helm#v-server-extravolumes) value in the Helm chart. -To configure the Vault service mesh provider, refer to [Vault as the Service Mesh Certificate Provider on Kubernetes](/docs/k8s/deployment-configurations/vault/data-integration/connect-ca). +To configure the Vault service mesh provider, refer to [Vault as the Service Mesh Certificate Provider on Kubernetes](/consul/docs/k8s/deployment-configurations/vault/data-integration/connect-ca). ## Configuring Vault as a Connect CA (Consul K8s 0.37.0 and earlier) @@ -28,16 +28,16 @@ If you use Vault 1.11.0+ as Consul's Connect CA, versions of Consul released bef The following instructions are only valid for Consul K8s CLI 0.37.0 and prior. It describes how to configure Vault as the Connect CA. You can configure other providers during initial bootstrap of the cluster by providing the appropriate [`ca_config`] and [`ca_provider`] values for your provider. --> **Auto-renewal:** If using Vault as your Connect CA, we strongly recommend Consul 1.8.5 or later, which includes support for token auto-renewal. If the Vault token is [renewable](https://www.vaultproject.io/api-docs/auth/token#renewable), then Consul automatically renews the token periodically. Otherwise, you must [manually rotate](#manually-rotating-vault-tokens) the Vault token before it expires. +-> **Auto-renewal:** If using Vault as your Connect CA, we strongly recommend Consul 1.8.5 or later, which includes support for token auto-renewal. If the Vault token is [renewable](/vault/api-docs/auth/token#renewable), then Consul automatically renews the token periodically. Otherwise, you must [manually rotate](#manually-rotating-vault-tokens) the Vault token before it expires. ### Primary Datacenter To configure Vault as a CA provider for Consul Connect, first, create a provider configuration JSON file. -Please refer to [Vault as a Connect CA](/docs/connect/ca/vault) for the configuration options. +Please refer to [Vault as a Connect CA](/consul/docs/connect/ca/vault) for the configuration options. You will need to provide a Vault token to the `token` property. -Please refer to [these docs](/docs/connect/ca/vault#token) for the permissions that the token needs to have. -This token should be [renewable](https://www.vaultproject.io/api-docs/auth/token#renewable). +Please refer to [these docs](/consul/docs/connect/ca/vault#token) for the permissions that the token needs to have. +This token should be [renewable](/vault/api-docs/auth/token#renewable). To provide a CA, you first need to create a Kubernetes secret containing the CA. For example, you may create a secret with the Vault CA like so: @@ -77,7 +77,7 @@ based on the Kubernetes secret for the Vault CA that we have created before. We will provide that secret later in the Helm values for our Consul cluster. ~> NOTE: If you have used Kubernetes CA to sign Vault's certificate, -such as shown in [Standalone Server with TLS](https://www.vaultproject.io/docs/platform/k8s/helm/examples/standalone-tls), +such as shown in [Standalone Server with TLS](/vault/docs/platform/k8s/helm/examples/standalone-tls), you don't need to create a Kubernetes secret with Vault's CA and can reference the CA directly by setting `ca_file` to `/var/run/secrets/kubernetes.io/serviceaccount/ca.crt`. @@ -112,7 +112,7 @@ We will provide this secret and the Vault CA secret, to the Consul server via th -Finally, [install](/docs/k8s/installation/install#installing-consul) the Helm chart using the above config file: +Finally, [install](/consul/docs/k8s/installation/install#installing-consul) the Helm chart using the above config file: ```shell-session $ helm install consul --values values.yaml hashicorp/consul @@ -176,7 +176,7 @@ Note that all secondary datacenters need to have access to the same Vault instan ### Manually Rotating Vault Tokens -If running Consul < 1.8.5 or using a Vault token that is not [renewable](https://www.vaultproject.io/api-docs/auth/token#renewable) +If running Consul < 1.8.5 or using a Vault token that is not [renewable](/vault/api-docs/auth/token#renewable) then you will need to manually renew or rotate the Vault token before it expires. #### Rotating Vault Token @@ -185,12 +185,12 @@ The [`ca_config`] and [`ca_provider`] options defined in the Consul agent configuration are only used when initially bootstrapping the cluster. Once the cluster is running, subsequent changes to the [`ca_provider`] config are **ignored**–even if `consul reload` is run or the servers are restarted. -To update any settings under these keys, you must use Consul's [Update CA Configuration](/api-docs/connect/ca#update-ca-configuration) API or the [`consul connect ca set-config`](/commands/connect/ca#set-config) command. +To update any settings under these keys, you must use Consul's [Update CA Configuration](/consul/api-docs/connect/ca#update-ca-configuration) API or the [`consul connect ca set-config`](/consul/commands/connect/ca#set-config) command. #### Renewing Vault Token -To renew the Vault token, use the [`vault token renew`](https://www.vaultproject.io/docs/commands/token/renew) CLI command +To renew the Vault token, use the [`vault token renew`](/vault/docs/commands/token/renew) CLI command or API. -[`ca_config`]: /docs/agent/config/config-files#connect_ca_config -[`ca_provider`]: /docs/agent/config/config-files#connect_ca_provider +[`ca_config`]: /consul/docs/agent/config/config-files#connect_ca_config +[`ca_provider`]: /consul/docs/agent/config/config-files#connect_ca_provider diff --git a/website/content/docs/k8s/connect/health.mdx b/website/content/docs/k8s/connect/health.mdx index 6daecdb138..654cb50342 100644 --- a/website/content/docs/k8s/connect/health.mdx +++ b/website/content/docs/k8s/connect/health.mdx @@ -17,10 +17,10 @@ For each Kubernetes pod that is connect-injected the following will be configure 1. A [Consul health check](/consul/api-docs/catalog#register-entity) is registered within Consul catalog. The Consul health check's state reflects the pod's readiness status. -1. If the pod is using [transparent proxy mode](/docs/connect/transparent-proxy), +1. If the pod is using [transparent proxy mode](/consul/docs/connect/transparent-proxy), the mutating webhook redirects all `http` based startup, liveness, and readiness probes in the pod through the Envoy proxy. This webhook is defined in the -[`ExposePaths` configuration](/docs/connect/registration/service-registration#expose-paths-configuration-reference) +[`ExposePaths` configuration](/consul/docs/connect/registration/service-registration#expose-paths-configuration-reference) for each probe so that kubelet can access the endpoint through the Envoy proxy. The mutation behavior can be disabled, by setting either the `consul.hashicorp.com/transparent-proxy-overwrite-probes` @@ -34,6 +34,6 @@ then use the respective service instance for service mesh traffic. In the case where no user defined health checks are assigned to a pod, the default behavior is that the Consul health check will be marked `passing` until the pod becomes unready. --> It is highly recommended to [enable TLS](/docs/k8s/helm#v-global-tls-enabled) for all production configurations to mitigate any +-> It is highly recommended to [enable TLS](/consul/docs/k8s/helm#v-global-tls-enabled) for all production configurations to mitigate any security concerns should the pod network ever be compromised. The controller makes calls across the network to Consul agents on all nodes so an attacker could potentially sniff ACL tokens *if those calls are not encrypted* via TLS. diff --git a/website/content/docs/k8s/connect/index.mdx b/website/content/docs/k8s/connect/index.mdx index fd78aad38b..7e30ab2be8 100644 --- a/website/content/docs/k8s/connect/index.mdx +++ b/website/content/docs/k8s/connect/index.mdx @@ -7,7 +7,7 @@ description: >- # How does Consul Service Mesh Work on Kubernetes? -[Consul Service Mesh](/docs/connect) is a feature built into to Consul that enables +[Consul Service Mesh](/consul/docs/connect) is a feature built into to Consul that enables automatic service-to-service authorization and connection encryption across your Consul services. Consul Service Mesh can be used with Kubernetes to secure pod communication with other pods and external Kubernetes services. _Consul Connect_ refers to the component in Consul that enables service mesh functionality. We sometimes use Connect to mean Consul service mesh throughout the documentation. @@ -17,14 +17,14 @@ your cluster, making configuration for Kubernetes automatic. This functionality is provided by the [consul-k8s project](https://github.com/hashicorp/consul-k8s) and can be automatically installed and configured using the -[Consul Helm chart](/docs/k8s/installation/install#helm-chart-installation). +[Consul Helm chart](/consul/docs/k8s/installation/install#helm-chart-installation). ## Usage -> **Important:** As of consul-k8s `v0.26.0` and Consul Helm `v0.32.0`, a Kubernetes service is required to run services on the Consul service mesh. -Installing Consul on Kubernetes with [`connect-inject` enabled](/docs/k8s/connect#installation-and-configuration) adds a sidecar to all pods. By default, it enables service mesh functionality with Consul Dataplane by injecting an Envoy proxy. You can also configure Consul to inject a client agent sidecar to connect to your service mesh. Refer to [Simplified Service Mesh with Consul Dataplane](/docs/connect/dataplane) for more information. +Installing Consul on Kubernetes with [`connect-inject` enabled](/consul/docs/k8s/connect#installation-and-configuration) adds a sidecar to all pods. By default, it enables service mesh functionality with Consul Dataplane by injecting an Envoy proxy. You can also configure Consul to inject a client agent sidecar to connect to your service mesh. Refer to [Simplified Service Mesh with Consul Dataplane](/consul/docs/connect/dataplane) for more information. ```yaml @@ -79,7 +79,7 @@ spec: The only change for Connect is the addition of the `consul.hashicorp.com/connect-inject` annotation. This enables injection for the Pod in this Deployment. The injector can also be -[configured](/docs/k8s/connect#installation-and-configuration) +[configured](/consul/docs/k8s/connect#installation-and-configuration) to automatically inject unless explicitly disabled, but the default installation requires opt-in using the annotation shown above. @@ -94,7 +94,7 @@ proxy. The client Connect proxy will use Consul service discovery to find all available upstream proxies and their public ports. In the example above, the server is listening on `:8080`. -By default, the Consul Service Mesh runs in [transparent proxy](/docs/connect/transparent-proxy) mode. +By default, the Consul Service Mesh runs in [transparent proxy](/consul/docs/connect/transparent-proxy) mode. This means that even though the server binds to all interfaces, the inbound and outbound connections will automatically go through to the sidecar proxy. It also allows you to use Kubernetes DNS like you normally would without the @@ -165,10 +165,10 @@ spec: By default when ACLs are enabled or when ACLs default policy is `allow`, Consul will automatically configure proxies with all upstreams from the same datacenter. When ACLs are enabled with default `deny` policy, -you must supply an [intention](/docs/connect/intentions) to tell Consul which upstream you need to talk to. +you must supply an [intention](/consul/docs/connect/intentions) to tell Consul which upstream you need to talk to. When upstreams are specified explicitly with the -[`consul.hashicorp.com/connect-service-upstreams` annotation](/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams), +[`consul.hashicorp.com/connect-service-upstreams` annotation](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams), the injector will also set environment variables `_CONNECT_SERVICE_HOST` and `_CONNECT_SERVICE_PORT` in every container in the Pod for every defined upstream. This is analogous to the standard Kubernetes service environment variables, but @@ -184,9 +184,9 @@ $ kubectl exec deploy/static-client -- curl --silent http://static-server/ "hello world" ``` -We can control access to the server using [intentions](/docs/connect/intentions). -If you use the Consul UI or [CLI](/commands/intention/create) to -create a deny [intention](/docs/connect/intentions) between +We can control access to the server using [intentions](/consul/docs/connect/intentions). +If you use the Consul UI or [CLI](/consul/commands/intention/create) to +create a deny [intention](/consul/docs/connect/intentions) between "static-client" and "static-server", connections are immediately rejected without updating either of the running pods. You can then remove this intention to allow connections again. @@ -372,10 +372,10 @@ provided by the [consul-k8s project](https://github.com/hashicorp/consul-k8s). This enables the automatic pod mutation shown in the usage section above. Installation of the mutating admission webhook is automated using the -[Helm chart](/docs/k8s/installation/install). +[Helm chart](/consul/docs/k8s/installation/install). To install the Connect injector, enable the Connect injection feature using -[Helm values](/docs/k8s/helm#configuration-values) and +[Helm values](/consul/docs/k8s/helm#configuration-values) and upgrade the installation using `helm upgrade` for existing installs or `helm install` for a fresh install. @@ -392,7 +392,7 @@ the injector runs in, enable injection by default, and more. ### Verifying the Installation To verify the installation, run the -["Accepting Inbound Connections"](/docs/k8s/connect#accepting-inbound-connections) +["Accepting Inbound Connections"](/consul/docs/k8s/connect#accepting-inbound-connections) example from the "Usage" section above. After running this example, run `kubectl get pod static-server --output yaml`. In the raw YAML output, you should see injected Connect containers and an annotation @@ -534,9 +534,9 @@ There are three options available: ### Consul Enterprise Namespace Upstreams -When [transparent proxy](/docs/connect/transparent-proxy) is enabled and ACLs are disabled, +When [transparent proxy](/consul/docs/connect/transparent-proxy) is enabled and ACLs are disabled, the upstreams will be configured automatically across Consul namespaces. -When ACLs are enabled, you must configure it by specifying an [intention](/docs/connect/intentions), +When ACLs are enabled, you must configure it by specifying an [intention](/consul/docs/connect/intentions), allowing services across Consul namespaces to talk to each other. If you wish to specify an upstream explicitly via the `consul.hashicorp.com/connect-service-upstreams` annotation, diff --git a/website/content/docs/k8s/connect/ingress-controllers.mdx b/website/content/docs/k8s/connect/ingress-controllers.mdx index e044bfee34..dcec16e170 100644 --- a/website/content/docs/k8s/connect/ingress-controllers.mdx +++ b/website/content/docs/k8s/connect/ingress-controllers.mdx @@ -7,9 +7,9 @@ description: >- # Configure Ingress Controllers for Consul on Kubernetes --> This topic requires Consul 1.10+, Consul-k8s 0.26+, Consul-helm 0.32+ configured with [Transparent Proxy](/docs/connect/transparent-proxy) mode enabled. In addition, this topic assumes that the reader is familiar with [Ingress Controllers](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/) on Kubernetes. +-> This topic requires Consul 1.10+, Consul-k8s 0.26+, Consul-helm 0.32+ configured with [Transparent Proxy](/consul/docs/connect/transparent-proxy) mode enabled. In addition, this topic assumes that the reader is familiar with [Ingress Controllers](https://kubernetes.io/docs/concepts/services-networking/ingress-controllers/) on Kubernetes. -~> If you are looking for a fully supported solution for ingress traffic into Consul Service Mesh, please visit [Consul API Gateway](/docs/api-gateway) for instruction on how to install Consul API Gateway along with Consul on Kubernetes. +~> If you are looking for a fully supported solution for ingress traffic into Consul Service Mesh, please visit [Consul API Gateway](/consul/docs/api-gateway) for instruction on how to install Consul API Gateway along with Consul on Kubernetes. This page describes a general approach for integrating Ingress Controllers with Consul on Kubernetes to secure traffic from the Controller to the backend services by deploying sidecars along with your Ingress Controller. This allows Consul to transparently secure traffic from the ingress point through the entire traffic flow of the service. @@ -19,13 +19,13 @@ A few steps are generally required to enable an Ingress controller to join the m * Enable connect-injection via an annotation on the Ingress Controller's deployment: `consul.hashicorp.com/connect-inject` is `true`. * Using the following annotations on the Ingress controller's deployment, set up exclusion rules for its ports. - * [`consul.hashicorp.com/transparent-proxy-exclude-inbound-ports`](/docs/k8s/annotations-and-labels#consul-hashicorp-com-transparent-proxy-exclude-inbound-ports) - Provides the ability to exclude a list of ports for + * [`consul.hashicorp.com/transparent-proxy-exclude-inbound-ports`](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-transparent-proxy-exclude-inbound-ports) - Provides the ability to exclude a list of ports for inbound traffic that the service exposes from redirection. Typical configurations would require all inbound service ports for the controller to be included in this list. - * [`consul.hashicorp.com/transparent-proxy-exclude-outbound-ports`](/docs/k8s/annotations-and-labels#consul-hashicorp-com-transparent-proxy-exclude-outbound-ports) - Provides the ability to exclude a list of ports for + * [`consul.hashicorp.com/transparent-proxy-exclude-outbound-ports`](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-transparent-proxy-exclude-outbound-ports) - Provides the ability to exclude a list of ports for outbound traffic that the service exposes from redirection. These would be outbound ports used by your ingress controller which expect to skip the mesh and talk to non-mesh services. - * [`consul.hashicorp.com/transparent-proxy-exclude-outbound-cidrs`](/docs/k8s/annotations-and-labels#consul-hashicorp-com-transparent-proxy-exclude-outbound-cidrs) - Provides the ability to exclude a list of CIDRs that + * [`consul.hashicorp.com/transparent-proxy-exclude-outbound-cidrs`](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-transparent-proxy-exclude-outbound-cidrs) - Provides the ability to exclude a list of CIDRs that the service communicates with for outbound requests from redirection. It is somewhat common that an Ingress controller will expect to make API calls to the Kubernetes service for service/endpoint management. As such including the ClusterIP of the Kubernetes service is common. diff --git a/website/content/docs/k8s/connect/ingress-gateways.mdx b/website/content/docs/k8s/connect/ingress-gateways.mdx index e0536a835e..1d2072ae3a 100644 --- a/website/content/docs/k8s/connect/ingress-gateways.mdx +++ b/website/content/docs/k8s/connect/ingress-gateways.mdx @@ -9,10 +9,10 @@ description: >- -> 1.9.0+: This feature is available in Consul versions 1.9.0 and higher -~> This topic requires familiarity with [Ingress Gateways](/docs/connect/gateways/ingress-gateway). +~> This topic requires familiarity with [Ingress Gateways](/consul/docs/connect/gateways/ingress-gateway). This page describes how to enable external access to Connect Service Mesh services running inside Kubernetes using Consul ingress gateways. -See [Ingress Gateways](/docs/connect/gateways/ingress-gateway) for more information on use-cases and how it works. +See [Ingress Gateways](/consul/docs/connect/gateways/ingress-gateway) for more information on use-cases and how it works. Adding an ingress gateway is a multi-step process that consists of the following steps: @@ -47,25 +47,25 @@ ingressGateways: ~> **Note:** this will create a public unauthenticated LoadBalancer in your cluster, please take appropriate security considerations. The YAML snippet is the launching point for a valid configuration that must be supplied when installing using the [official consul-helm chart](https://hub.helm.sh/charts/hashicorp/consul). -Information on additional options can be found in the [Helm reference](/docs/k8s/helm). -Configuration options for ingress gateways reside under the [ingressGateways](/docs/k8s/helm#v-ingressgateways) entry. +Information on additional options can be found in the [Helm reference](/consul/docs/k8s/helm). +Configuration options for ingress gateways reside under the [ingressGateways](/consul/docs/k8s/helm#v-ingressgateways) entry. The gateways stanza is where you will define and configure the set of ingress gateways you want deployed to your environment. The only required field for each entry is `name`, though entries may contain any of the fields found in the `defaults` stanza. Values in this section override the values from the defaults stanza for the given ingress gateway with one exception: the annotations from the defaults stanza will be _appended_ to any user-defined annotations defined in the gateways stanza rather than being overridden. -Please refer to the ingress gateway configuration [documentation](/docs/k8s/helm#v-ingressgateways-defaults) for a detailed explanation of each option. +Please refer to the ingress gateway configuration [documentation](/consul/docs/k8s/helm#v-ingressgateways-defaults) for a detailed explanation of each option. ## Deploying the Helm chart Ensure you have the latest consul-helm chart and install Consul via helm using the following -[guide](/docs/k8s/installation/install#installing-consul) while being sure to provide the yaml configuration +[guide](/consul/docs/k8s/installation/install#installing-consul) while being sure to provide the yaml configuration as previously discussed. ## Configuring the gateway Now that Consul has been installed with ingress gateways enabled, -you can configure the gateways via the [`IngressGateway`](/docs/connect/config-entries/ingress-gateway) custom resource. +you can configure the gateways via the [`IngressGateway`](/consul/docs/connect/config-entries/ingress-gateway) custom resource. Here is an example `IngressGateway` resource: @@ -88,7 +88,7 @@ spec: ~> **Note:** The 'name' field for the IngressGateway resource must match the name specified when creating the gateway in the Helm chart. In the above example, the -name "ingress-gateway" is the [default name](/docs/k8s/helm#v-ingressgateways-gateways-name) +name "ingress-gateway" is the [default name](/consul/docs/k8s/helm#v-ingressgateways-gateways-name) used by the Helm chart when enabling ingress gateways. Apply the `IngressGateway` resource with `kubectl apply`: @@ -99,7 +99,7 @@ ingressgateway.consul.hashicorp.com/ingress-gateway created ``` Since we're using `protocol: http`, we also need to set the protocol of our service -`static-server` to http. To do that, we create a [`ServiceDefaults`](/docs/connect/config-entries/service-defaults) custom resource: +`static-server` to http. To do that, we create a [`ServiceDefaults`](/consul/docs/connect/config-entries/service-defaults) custom resource: @@ -138,7 +138,7 @@ ingress-gateway True 13m You can confirm the ingress gateways have been configured as expected by viewing the ingress-gateway service instances in the Consul UI. -To view the UI, use the `kubectl port-forward` command. See [Viewing The Consul UI](/docs/k8s/installation/install#viewing-the-consul-ui) +To view the UI, use the `kubectl port-forward` command. See [Viewing The Consul UI](/consul/docs/k8s/installation/install#viewing-the-consul-ui) for full instructions. Once you've port-forwarded to the UI, navigate to the Ingress Gateway instances: [http://localhost:8500/ui/dc1/services/ingress-gateway/instances](http://localhost:8500/ui/dc1/services/ingress-gateway/instances) @@ -147,10 +147,10 @@ If TLS is enabled, use [https://localhost:8501/ui/dc1/services/ingress-gateway/i ## Defining an Intention -If ACLs are enabled (via the `global.acls.manageSystemACLs` setting), you must define an [intention](/docs/connect/intentions) +If ACLs are enabled (via the `global.acls.manageSystemACLs` setting), you must define an [intention](/consul/docs/connect/intentions) to allow the ingress gateway to route to the upstream services defined in the `IngressGateway` resource (in the example above the upstream service is `static-server`). -To create an intention that allows the ingress gateway to route to the service `static-server`, create a [`ServiceIntentions`](/docs/connect/config-entries/service-intentions) +To create an intention that allows the ingress gateway to route to the service `static-server`, create a [`ServiceIntentions`](/consul/docs/connect/config-entries/service-intentions) resource: @@ -177,7 +177,7 @@ $ kubectl apply --filename service-intentions.yaml serviceintentions.consul.hashicorp.com/ingress-gateway created ``` -For detailed instructions on how to configure zero-trust networking with intentions please refer to this [guide](https://learn.hashicorp.com/tutorials/consul/service-mesh-zero-trust-network?utm_source=docs). +For detailed instructions on how to configure zero-trust networking with intentions please refer to this [guide](/consul/tutorials/kubernetes-features/service-mesh-zero-trust-network?utm_source=docs). ## Deploying your application to Kubernetes diff --git a/website/content/docs/k8s/connect/observability/metrics.mdx b/website/content/docs/k8s/connect/observability/metrics.mdx index 8b80ed9e34..c8db578268 100644 --- a/website/content/docs/k8s/connect/observability/metrics.mdx +++ b/website/content/docs/k8s/connect/observability/metrics.mdx @@ -30,7 +30,7 @@ The diagram below illustrates how the metrics integration works when merging is [![Metrics Merging Architecture](/img/metrics-arch.png)](/img/metrics-arch.png) --> -Connect service metrics can be configured with the Helm values nested under [`connectInject.metrics`](/docs/k8s/helm#v-connectinject-metrics). +Connect service metrics can be configured with the Helm values nested under [`connectInject.metrics`](/consul/docs/k8s/helm#v-connectinject-metrics). Metrics and metrics merging can be enabled by default for all connect-injected Pods with the following Helm values: @@ -110,7 +110,7 @@ global: ## Metrics in the UI Topology Visualization -Consul's built-in UI has a topology visualization for services that are part of the Consul service mesh. The topology visualization has the ability to fetch basic metrics from a metrics provider for each service and display those metrics as part of the [topology visualization](/docs/connect/observability/ui-visualization). +Consul's built-in UI has a topology visualization for services that are part of the Consul service mesh. The topology visualization has the ability to fetch basic metrics from a metrics provider for each service and display those metrics as part of the [topology visualization](/consul/docs/connect/observability/ui-visualization). The diagram below illustrates how the UI displays service metrics for a sample application: diff --git a/website/content/docs/k8s/connect/terminating-gateways.mdx b/website/content/docs/k8s/connect/terminating-gateways.mdx index 517aa9a454..1da48d0a54 100644 --- a/website/content/docs/k8s/connect/terminating-gateways.mdx +++ b/website/content/docs/k8s/connect/terminating-gateways.mdx @@ -16,9 +16,9 @@ Adding a terminating gateway is a multi-step process: ## Requirements -- [Consul](/docs/install#install-consul) -- [Consul on Kubernetes CLI](/docs/k8s/k8s-cli) -- Familiarity with [Terminating Gateways](/docs/connect/gateways/terminating-gateway) +- [Consul](/consul/docs/install#install-consul) +- [Consul on Kubernetes CLI](/consul/docs/k8s/k8s-cli) +- Familiarity with [Terminating Gateways](/consul/docs/connect/gateways/terminating-gateway) ## Update the Helm chart with terminating gateway configuration options @@ -37,7 +37,7 @@ terminatingGateways: ## Deploying the Helm chart -The Helm chart may be deployed using the [Consul on Kubernetes CLI](/docs/k8s/k8s-cli). +The Helm chart may be deployed using the [Consul on Kubernetes CLI](/consul/docs/k8s/k8s-cli). ```shell-session $ consul-k8s install -f values.yaml @@ -88,20 +88,20 @@ Registering the external services with Consul is a multi-step process: - Register external services with Consul - Update the terminating gateway ACL token if ACLs are enabled -- Create a [`TerminatingGateway`](/docs/connect/config-entries/terminating-gateway) resource to configure the terminating gateway -- Create a [`ServiceIntentions`](/docs/connect/config-entries/service-intentions) resource to allow access from services in the mesh to external service +- Create a [`TerminatingGateway`](/consul/docs/connect/config-entries/terminating-gateway) resource to configure the terminating gateway +- Create a [`ServiceIntentions`](/consul/docs/connect/config-entries/service-intentions) resource to allow access from services in the mesh to external service - Define upstream annotations for any services that need to talk to the external services ### Register external services with Consul You may register an external service with Consul using `ServiceDefaults` if -[`TransparentProxy`](/docs/connect/transparent-proxy) is enabled. Otherwise, +[`TransparentProxy`](/consul/docs/connect/transparent-proxy) is enabled. Otherwise, you may register the service as a node in the Consul catalog. -The [`destination`](/docs/connect/config-entries/service-defaults#terminating-gateway-destination) field of the `ServiceDefaults` Custom Resource Definition (CRD) allows clients to dial an external service directly. For this method to work, [`TransparentProxy`](/docs/connect/transparent-proxy) must be enabled. +The [`destination`](/consul/docs/connect/config-entries/service-defaults#terminating-gateway-destination) field of the `ServiceDefaults` Custom Resource Definition (CRD) allows clients to dial an external service directly. For this method to work, [`TransparentProxy`](/consul/docs/connect/transparent-proxy) must be enabled. The following table describes traffic behaviors when using the `destination` field to route traffic through a terminating gateway: | External Services Layer | Client dials | Client uses TLS | Allowed | Notes | @@ -118,7 +118,7 @@ The following table describes traffic behaviors when using the `destination` fie You can provide a `caFile` to secure traffic that connect to external services through the terminating gateway. Refer to [Create the configuration entry for the terminating gateway](#create-the-configuration-entry-for-the-terminating-gateway) for details. --> **Note:** Regardless of the `protocol` specified in the `ServiceDefaults`, [L7 intentions](/docs/connect/config-entries/service-intentions#permissions) are not currently supported with `ServiceDefaults` destinations. +-> **Note:** Regardless of the `protocol` specified in the `ServiceDefaults`, [L7 intentions](/consul/docs/connect/config-entries/service-intentions#permissions) are not currently supported with `ServiceDefaults` destinations. Create a `ServiceDefaults` custom resource for the external service: @@ -256,7 +256,7 @@ Policies: ### Create the configuration entry for the terminating gateway -Once the roles have been updated, create the [TerminatingGateway](/docs/connect/config-entries/terminating-gateway) +Once the roles have been updated, create the [TerminatingGateway](/consul/docs/connect/config-entries/terminating-gateway) resource to configure the terminating gateway: @@ -273,9 +273,9 @@ spec: -If TLS is enabled for external services registered through the Consul catalog and you are not using [transparent proxy `destination`](#register-an-external-service-as-a-destination), you must include the [`caFile`](/docs/connect/config-entries/terminating-gateway#cafile) parameter that points to the system trust store of the terminating gateway container. +If TLS is enabled for external services registered through the Consul catalog and you are not using [transparent proxy `destination`](#register-an-external-service-as-a-destination), you must include the [`caFile`](/consul/docs/connect/config-entries/terminating-gateway#cafile) parameter that points to the system trust store of the terminating gateway container. By default, the trust store is located in the `/etc/ssl/certs/ca-certificates.crt` directory. -Configure the [`caFile`](/docs/connect/config-entries/terminating-gateway#cafile) parameter in the `TerminatingGateway` config entry to point to the `/etc/ssl/cert.pem` directory if TLS is enabled and you are using one of the following components: +Configure the [`caFile`](/consul/docs/connect/config-entries/terminating-gateway#cafile) parameter in the `TerminatingGateway` config entry to point to the `/etc/ssl/cert.pem` directory if TLS is enabled and you are using one of the following components: - Consul Helm chart 0.43 or older - An Envoy image with an alpine base image @@ -285,7 +285,7 @@ Apply the `TerminatingGateway` resource with `kubectl apply`: $ kubectl apply --filename terminating-gateway.yaml ``` -If using ACLs and TLS, create a [`ServiceIntentions`](/docs/connect/config-entries/service-intentions) resource to allow access from services in the mesh to the external service: +If using ACLs and TLS, create a [`ServiceIntentions`](/consul/docs/connect/config-entries/service-intentions) resource to allow access from services in the mesh to the external service: @@ -304,7 +304,7 @@ spec: --> **NOTE**: [L7 Intentions](/docs/connect/config-entries/service-intentions#permissions) are not currently supported for `ServiceDefaults` destinations. +-> **NOTE**: [L7 Intentions](/consul/docs/connect/config-entries/service-intentions#permissions) are not currently supported for `ServiceDefaults` destinations. Apply the `ServiceIntentions` resource with `kubectl apply`: diff --git a/website/content/docs/k8s/crds/index.mdx b/website/content/docs/k8s/crds/index.mdx index 43387ae312..342fe1aaa4 100644 --- a/website/content/docs/k8s/crds/index.mdx +++ b/website/content/docs/k8s/crds/index.mdx @@ -7,25 +7,25 @@ description: >- # Custom Resource Definitions (CRDs) for Consul on Kubernetes -This topic describes how to manage Consul [configuration entries](/docs/agent/config-entries) +This topic describes how to manage Consul [configuration entries](/consul/docs/agent/config-entries) with Kubernetes Custom Resources. Configuration entries provide cluster-wide defaults for the service mesh. ## Supported Configuration Entries You can specify the following values in the `kind` field. Click on a configuration entry to view its documentation: -- [`Mesh`](/docs/connect/config-entries/mesh) -- [`ExportedServices`](/docs/connect/config-entries/exported-services) -- [`PeeringAcceptor`](/docs/connect/cluster-peering/k8s#peeringacceptor) -- [`PeeringDialer`](/docs/connect/cluster-peering/k8s#peeringdialer) -- [`ProxyDefaults`](/docs/connect/config-entries/proxy-defaults) -- [`ServiceDefaults`](/docs/connect/config-entries/service-defaults) -- [`ServiceSplitter`](/docs/connect/config-entries/service-splitter) -- [`ServiceRouter`](/docs/connect/config-entries/service-router) -- [`ServiceResolver`](/docs/connect/config-entries/service-resolver) -- [`ServiceIntentions`](/docs/connect/config-entries/service-intentions) -- [`IngressGateway`](/docs/connect/config-entries/ingress-gateway) -- [`TerminatingGateway`](/docs/connect/config-entries/terminating-gateway) +- [`Mesh`](/consul/docs/connect/config-entries/mesh) +- [`ExportedServices`](/consul/docs/connect/config-entries/exported-services) +- [`PeeringAcceptor`](/consul/docs/connect/cluster-peering/k8s#peeringacceptor) +- [`PeeringDialer`](/consul/docs/connect/cluster-peering/k8s#peeringdialer) +- [`ProxyDefaults`](/consul/docs/connect/config-entries/proxy-defaults) +- [`ServiceDefaults`](/consul/docs/connect/config-entries/service-defaults) +- [`ServiceSplitter`](/consul/docs/connect/config-entries/service-splitter) +- [`ServiceRouter`](/consul/docs/connect/config-entries/service-router) +- [`ServiceResolver`](/consul/docs/connect/config-entries/service-resolver) +- [`ServiceIntentions`](/consul/docs/connect/config-entries/service-intentions) +- [`IngressGateway`](/consul/docs/connect/config-entries/ingress-gateway) +- [`TerminatingGateway`](/consul/docs/connect/config-entries/terminating-gateway) ## Installation @@ -46,7 +46,7 @@ Hang tight while we grab the latest from your chart repositories... Update Complete. ⎈Happy Helming!⎈ ``` -Refer to [Install with Helm Chart](/docs/k8s/installation/install) for further installation +Refer to [Install with Helm Chart](/consul/docs/k8s/installation/install) for further installation instructions. **Note**: Configuration entries require `connectInject` to be enabled, which is a default behavior in the official Helm Chart. If you disabled this setting, you must re-enable it to use CRDs. @@ -54,7 +54,7 @@ instructions. ## Upgrading An Existing Cluster to CRDs If you have an existing Consul cluster running on Kubernetes you may need to perform -extra steps to migrate to CRDs. Refer to [Upgrade An Existing Cluster to CRDs](/docs/k8s/crds/upgrade-to-crds) for full instructions. +extra steps to migrate to CRDs. Refer to [Upgrade An Existing Cluster to CRDs](/consul/docs/k8s/crds/upgrade-to-crds) for full instructions. ## Usage @@ -77,7 +77,7 @@ EOF servicedefaults.consul.hashicorp.com/foo created ``` -Refer to [Configuration Entries](/docs/agent/config-entries) for detailed schema documentation. +Refer to [Configuration Entries](/consul/docs/agent/config-entries) for detailed schema documentation. ### Get @@ -261,7 +261,7 @@ The details on each configuration are: in the Consul namespace `web-ns`. In the same vein, a `ServiceDefaults` custom resource with name `web` in Kubernetes namespace `web-ns` configures that same service. - This is configured with [`connectInject.consulNamespaces`](/docs/k8s/helm#v-connectinject-consulnamespaces): + This is configured with [`connectInject.consulNamespaces`](/consul/docs/k8s/helm#v-connectinject-consulnamespaces): @@ -282,7 +282,7 @@ The details on each configuration are: in the Consul namespace `k8s-web-ns`. In the same vein, a `ServiceDefaults` custom resource with name `web` in Kubernetes namespace `web-ns` configures that same service. - This is configured with [`connectInject.consulNamespaces`](/docs/k8s/helm#v-connectinject-consulnamespaces): + This is configured with [`connectInject.consulNamespaces`](/consul/docs/k8s/helm#v-connectinject-consulnamespaces): @@ -309,7 +309,7 @@ The details on each configuration are: service is running in Kubernetes namespace `web-ns` because the `ServiceDefaults` resource ends up registered into the same Consul namespace `my-ns`. - This is configured with [`connectInject.consulNamespaces`](/docs/k8s/helm#v-connectinject-consulnamespaces): + This is configured with [`connectInject.consulNamespaces`](/consul/docs/k8s/helm#v-connectinject-consulnamespaces): diff --git a/website/content/docs/k8s/crds/upgrade-to-crds.mdx b/website/content/docs/k8s/crds/upgrade-to-crds.mdx index e583f31697..755b50f203 100644 --- a/website/content/docs/k8s/crds/upgrade-to-crds.mdx +++ b/website/content/docs/k8s/crds/upgrade-to-crds.mdx @@ -50,10 +50,10 @@ connectInject: defaultProtocol: 'http' # or any value ``` -Now you must use [custom resources](/docs/k8s/crds) to manage the protocol for +Now you must use [custom resources](/consul/docs/k8s/crds) to manage the protocol for new and existing services: -1. To upgrade, first ensure you're running Consul >= 1.9.0. See [Consul Version Upgrade](/docs/k8s/upgrade#consul-version-upgrade) +1. To upgrade, first ensure you're running Consul >= 1.9.0. See [Consul Version Upgrade](/consul/docs/k8s/upgrade#consul-version-upgrade) for more information on how to upgrade Consul versions. This version is required to support custom resources. @@ -61,7 +61,7 @@ new and existing services: 1. Next, modify your Helm values: 1. Remove the `defaultProtocol` config. This won't affect existing services. 1. Now you can upgrade your Helm chart to the latest version with the new Helm values. -1. From now on, any new service will require a [`ServiceDefaults`](/docs/connect/config-entries/service-defaults) +1. From now on, any new service will require a [`ServiceDefaults`](/consul/docs/connect/config-entries/service-defaults) resource to set its protocol: ```yaml @@ -122,7 +122,7 @@ You will need to perform the following steps to upgrade: effect on your existing cluster because this config is only read when the cluster is **first created**. 1. You can then upgrade the Helm chart. -1. If you later wish to _change_ the mode or any other setting in [`proxy-defaults`](/docs/connect/config-entries/proxy-defaults), you will need +1. If you later wish to _change_ the mode or any other setting in [`proxy-defaults`](/consul/docs/connect/config-entries/proxy-defaults), you will need to follow the [Migrating Config Entries](#migrating-config-entries) instructions to migrate your `proxy-defaults` config entry to a `ProxyDefaults` resource. @@ -151,7 +151,7 @@ spec: You will need to perform the following steps to upgrade: -1. Ensure you're running Consul >= 1.9.0. See [Consul Version Upgrade](/docs/k8s/upgrade#consul-version-upgrade) +1. Ensure you're running Consul >= 1.9.0. See [Consul Version Upgrade](/consul/docs/k8s/upgrade#consul-version-upgrade) for more information on how to upgrade Consul versions. This version is required to support custom resources. @@ -160,7 +160,7 @@ You will need to perform the following steps to upgrade: effect on the deployments because the annotation was only used when the service was first created. 1. Now you can upgrade your Helm chart to the latest version. -1. From now on, any new service will require a [`ServiceDefaults`](/docs/connect/config-entries/service-defaults) +1. From now on, any new service will require a [`ServiceDefaults`](/consul/docs/connect/config-entries/service-defaults) resource to set its protocol: ```yaml diff --git a/website/content/docs/k8s/deployment-configurations/clients-outside-kubernetes.mdx b/website/content/docs/k8s/deployment-configurations/clients-outside-kubernetes.mdx index eebd2dd81d..cb57f16526 100644 --- a/website/content/docs/k8s/deployment-configurations/clients-outside-kubernetes.mdx +++ b/website/content/docs/k8s/deployment-configurations/clients-outside-kubernetes.mdx @@ -12,7 +12,7 @@ Services running on non-Kubernetes nodes can join a Consul cluster running withi ## Auto-join The recommended way to join a cluster running within Kubernetes is to -use the ["k8s" cloud auto-join provider](/docs/install/cloud-auto-join#kubernetes-k8s). +use the ["k8s" cloud auto-join provider](/consul/docs/install/cloud-auto-join#kubernetes-k8s). The auto-join provider dynamically discovers IP addresses to join using the Kubernetes API. It authenticates with Kubernetes using a standard @@ -21,7 +21,7 @@ as well as self-hosted installations. The token in the `kubeconfig` file needs to have permissions to list pods in the namespace where Consul servers are deployed. -The auto-join string below joins a Consul server agent to a cluster using the [official Helm chart](/docs/k8s/helm): +The auto-join string below joins a Consul server agent to a cluster using the [official Helm chart](/consul/docs/k8s/helm): ```shell-session $ consul agent -retry-join 'provider=k8s label_selector="app=consul,component=server"' @@ -46,7 +46,7 @@ For more information, refer to [Azure AKS CNI](https://docs.microsoft.com/en-us/ [AWS EKS CNI](https://docs.aws.amazon.com/eks/latest/userguide/pod-networking.html) and [GKE VPC-native clusters](https://cloud.google.com/kubernetes-engine/docs/concepts/alias-ips). -To join external agents with Consul on Kubernetes deployments installed with default values through the [official Helm chart](/docs/k8s/helm): +To join external agents with Consul on Kubernetes deployments installed with default values through the [official Helm chart](/consul/docs/k8s/helm): 1. Make sure the pod IPs of the servers in Kubernetes are routable from the VM and that the VM can access port 8301 (for gossip) and @@ -88,7 +88,7 @@ To join external agents with Consul on Kubernetes deployments installed with def If your external VMs cannot connect to Kubernetes pod IPs but they can connect to the internal host IPs of the nodes in the Kubernetes cluster, you can join the two by exposing ports on the host IP instead. - 1. Install the [official Helm chart](/docs/k8s/helm) with the following values: + 1. Install the [official Helm chart](/consul/docs/k8s/helm) with the following values: ```yaml client: exposeGossipPorts: true # exposes client gossip ports as hostPorts diff --git a/website/content/docs/k8s/deployment-configurations/consul-enterprise.mdx b/website/content/docs/k8s/deployment-configurations/consul-enterprise.mdx index 75f65c58d7..48c4db1fa0 100644 --- a/website/content/docs/k8s/deployment-configurations/consul-enterprise.mdx +++ b/website/content/docs/k8s/deployment-configurations/consul-enterprise.mdx @@ -11,7 +11,7 @@ You can use this Helm chart to deploy Consul Enterprise by following a few extra Find the license file that you received in your welcome email. It should have a `.hclic` extension. You will use the contents of this file to create a Kubernetes secret before installing the Helm chart. --> **Note:** This guide assumes you are storing your license as a Kubernetes Secret. If you would like to store the enterprise license in Vault, please reference [Storing the Enterprise License in Vault](/docs/k8s/deployment-configuration/vault/data-integration/enterprise-license). +-> **Note:** This guide assumes you are storing your license as a Kubernetes Secret. If you would like to store the enterprise license in Vault, please reference [Storing the Enterprise License in Vault](/consul/docs/k8s/deployment-configuration/vault/data-integration/enterprise-license). You can use the following commands to create the secret with name `consul-ent-license` and key `key`: diff --git a/website/content/docs/k8s/deployment-configurations/multi-cluster/index.mdx b/website/content/docs/k8s/deployment-configurations/multi-cluster/index.mdx index dc412e1a74..fdf5c6d945 100644 --- a/website/content/docs/k8s/deployment-configurations/multi-cluster/index.mdx +++ b/website/content/docs/k8s/deployment-configurations/multi-cluster/index.mdx @@ -12,8 +12,8 @@ When datacenters are joined, Consul servers in each datacenter can communicate with one another. This enables the following features: - Services on all clusters can make calls to each other through Consul Service Mesh. -- [Intentions](/docs/connect/intentions) can be used to enforce rules about which services can communicate across all clusters. -- [L7 Routing Rules](/docs/connect/l7-traffic) can enable multi-cluster failover +- [Intentions](/consul/docs/connect/intentions) can be used to enforce rules about which services can communicate across all clusters. +- [L7 Routing Rules](/consul/docs/connect/l7-traffic) can enable multi-cluster failover and traffic splitting. - The Consul UI has a drop-down menu that lets you navigate between datacenters. @@ -74,6 +74,6 @@ There are three networking requirements: ## Next Steps Now that you have an overview of federation, proceed to either the -[Federation Between Kubernetes Clusters](/docs/k8s/deployment-configurations/multi-cluster/kubernetes) -or [Federation Between VMs and Kubernetes](/docs/k8s/deployment-configurations/multi-cluster/vms-and-kubernetes) +[Federation Between Kubernetes Clusters](/consul/docs/k8s/deployment-configurations/multi-cluster/kubernetes) +or [Federation Between VMs and Kubernetes](/consul/docs/k8s/deployment-configurations/multi-cluster/vms-and-kubernetes) pages depending on your use case. diff --git a/website/content/docs/k8s/deployment-configurations/multi-cluster/kubernetes.mdx b/website/content/docs/k8s/deployment-configurations/multi-cluster/kubernetes.mdx index ac4fa3dcbf..46aa7979e5 100644 --- a/website/content/docs/k8s/deployment-configurations/multi-cluster/kubernetes.mdx +++ b/website/content/docs/k8s/deployment-configurations/multi-cluster/kubernetes.mdx @@ -9,11 +9,11 @@ description: >- -> **1.8.0+:** This feature is available in Consul versions 1.8.0 and higher -~> This topic requires familiarity with [Mesh Gateways](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters) and [WAN Federation Via Mesh Gateways](/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways). +~> This topic requires familiarity with [Mesh Gateways](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters) and [WAN Federation Via Mesh Gateways](/consul/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways). --> Looking for a step-by-step guide? Complete the [Secure and Route Service Mesh Communication Across Kubernetes](https://learn.hashicorp.com/tutorials/consul/kubernetes-mesh-gateways?utm_source=docs) tutorial to learn more. +-> Looking for a step-by-step guide? Complete the [Secure and Route Service Mesh Communication Across Kubernetes](/consul/tutorials/kubernetes/kubernetes-mesh-gateways?utm_source=docs) tutorial to learn more. -This page describes how to federate multiple Kubernetes clusters. See [Multi-Cluster Overview](/docs/k8s/deployment-configurations/multi-cluster) +This page describes how to federate multiple Kubernetes clusters. See [Multi-Cluster Overview](/consul/docs/k8s/deployment-configurations/multi-cluster) for more information on use-cases and how it works. ## Primary Datacenter @@ -109,9 +109,9 @@ Modifications: 1. The default mesh gateway configuration creates a Kubernetes Load Balancer service. If you wish to customize the mesh gateway, for example using a Node Port service or a custom DNS entry, - see the [Helm reference](/docs/k8s/helm#v-meshgateway) for that setting. + see the [Helm reference](/consul/docs/k8s/helm#v-meshgateway) for that setting. -With your `values.yaml` ready to go, follow our [Installation Guide](/docs/k8s/installation/install) +With your `values.yaml` ready to go, follow our [Installation Guide](/consul/docs/k8s/installation/install) to install Consul on your primary cluster. -> **NOTE:** You must be using consul-helm 0.21.0+. To update, run `helm repo update`. @@ -139,7 +139,7 @@ meshGateway: -1. `global.tls.enabled` must be `true`. See [Configuring TLS on an Existing Cluster](/docs/k8s/operations/tls-on-existing-cluster) +1. `global.tls.enabled` must be `true`. See [Configuring TLS on an Existing Cluster](/consul/docs/k8s/operations/tls-on-existing-cluster) for more information on safely upgrading a cluster to use TLS. If you've set `enableAutoEncrypt: true`, this is also supported. @@ -151,16 +151,16 @@ If you've set `enableAutoEncrypt: true`, this is also supported. with the primary. 1. Mesh Gateways are enabled with the default configuration. The default configuration creates a Kubernetes Load Balancer service. If you wish to customize the - mesh gateway, see the [Helm reference](/docs/k8s/helm#v-meshgateway) for that setting. + mesh gateway, see the [Helm reference](/consul/docs/k8s/helm#v-meshgateway) for that setting. -With the above settings added to your existing config, follow the [Upgrading](/docs/k8s/upgrade) +With the above settings added to your existing config, follow the [Upgrading](/consul/docs/k8s/upgrade) guide to upgrade your cluster and then come back to the [Federation Secret](#federation-secret) section. -> **NOTE:** You must be using consul-helm 0.21.0+. #### ProxyDefaults -If you are using consul-helm 0.30.0+ you must also create a [`ProxyDefaults`](/docs/connect/config-entries/proxy-defaults) +If you are using consul-helm 0.30.0+ you must also create a [`ProxyDefaults`](/consul/docs/connect/config-entries/proxy-defaults) resource to configure Consul to use the mesh gateways for service mesh traffic. ```yaml @@ -262,8 +262,8 @@ The automatically generated federation secret contains: - **Consul server config** - This is a JSON snippet that must be used as part of the server config for secondary datacenters. It sets: - - [`primary_datacenter`](/docs/agent/config/config-files#primary_datacenter) to the name of the primary datacenter. - - [`primary_gateways`](/docs/agent/config/config-files#primary_gateways) to an array of IPs or hostnames + - [`primary_datacenter`](/consul/docs/agent/config/config-files#primary_datacenter) to the name of the primary datacenter. + - [`primary_gateways`](/consul/docs/agent/config/config-files#primary_gateways) to an array of IPs or hostnames for the mesh gateways in the primary datacenter. These are the addresses that Consul servers in secondary clusters will use to communicate with the primary datacenter. @@ -288,7 +288,7 @@ The automatically generated federation secret contains: If ACLs are enabled, you must next determine the Kubernetes API URL for each secondary cluster. The API URL of the secondary cluster must be specified in the config files for each secondary cluster because they need to create global Consul ACL tokens (tokens that are valid in all datacenters) and these tokens can only be created -by the primary datacenter. By setting the API URL, the secondary cluster will configure a [Consul auth method](/docs/security/acl/auth-methods) +by the primary datacenter. By setting the API URL, the secondary cluster will configure a [Consul auth method](/consul/docs/security/acl/auth-methods) in the primary cluster so that components in the secondary cluster can use their Kubernetes ServiceAccount tokens to retrieve global Consul ACL tokens from the primary. @@ -407,9 +407,9 @@ Modifications: 1. The default mesh gateway configuration creates a Kubernetes Load Balancer service. If you wish to customize the mesh gateway, for example using a Node Port service or a custom DNS entry, - see the [Helm reference](/docs/k8s/helm#v-meshgateway) for that setting. + see the [Helm reference](/consul/docs/k8s/helm#v-meshgateway) for that setting. -With your `values.yaml` ready to go, follow our [Installation Guide](/docs/k8s/installation/install) +With your `values.yaml` ready to go, follow our [Installation Guide](/consul/docs/k8s/installation/install) to install Consul on your secondary cluster(s). ## Verifying Federation @@ -447,7 +447,7 @@ You can switch kubectl contexts and run the same command in `dc2` with the flag ### Consul UI We can also use the Consul UI to verify federation. -See [Viewing the Consul UI](/docs/k8s/installation/install#viewing-the-consul-ui) +See [Viewing the Consul UI](/consul/docs/k8s/installation/install#viewing-the-consul-ui) for instructions on how to view the UI. ~> NOTE: If ACLs are enabled, your kubectl context must be in the primary datacenter @@ -460,12 +460,12 @@ in the top left: ## Next Steps -With your Kubernetes clusters federated, complete the [Secure and Route Service Mesh Communication Across Kubernetes](https://learn.hashicorp.com/tutorials/consul/kubernetes-mesh-gateways?utm_source=docs#deploy-microservices) tutorial to learn how to use Consul service mesh to +With your Kubernetes clusters federated, complete the [Secure and Route Service Mesh Communication Across Kubernetes](/consul/tutorials/kubernetes/kubernetes-mesh-gateways?utm_source=docs#deploy-microservices) tutorial to learn how to use Consul service mesh to route between services deployed on each cluster. -You can also read our in-depth documentation on [Consul Service Mesh In Kubernetes](/docs/k8s/connect). +You can also read our in-depth documentation on [Consul Service Mesh In Kubernetes](/consul/docs/k8s/connect). -If you are still considering a move to Kubernetes, or to Consul on Kubernetes specifically, our [Migrate to Microservices with Consul Service Mesh on Kubernetes](https://learn.hashicorp.com/collections/consul/microservices?utm_source=docs) +If you are still considering a move to Kubernetes, or to Consul on Kubernetes specifically, our [Migrate to Microservices with Consul Service Mesh on Kubernetes](/consul/tutorials/microservices?utm_source=docs) collection uses an example application written by a fictional company to illustrate why and how organizations can migrate from monolith to microservices using Consul service mesh on Kubernetes. The case study in this collection should provide information valuable for understanding how to develop services that leverage Consul during any stage diff --git a/website/content/docs/k8s/deployment-configurations/multi-cluster/vms-and-kubernetes.mdx b/website/content/docs/k8s/deployment-configurations/multi-cluster/vms-and-kubernetes.mdx index 4e56e8b015..6486630dae 100644 --- a/website/content/docs/k8s/deployment-configurations/multi-cluster/vms-and-kubernetes.mdx +++ b/website/content/docs/k8s/deployment-configurations/multi-cluster/vms-and-kubernetes.mdx @@ -9,18 +9,18 @@ description: >- -> **1.8.0+:** This feature is available in Consul versions 1.8.0 and higher -~> This topic requires familiarity with [Mesh Gateways](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters) and [WAN Federation Via Mesh Gateways](/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways). +~> This topic requires familiarity with [Mesh Gateways](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters) and [WAN Federation Via Mesh Gateways](/consul/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways). Consul datacenters running on non-kubernetes platforms like VMs or bare metal can be federated with Kubernetes datacenters. Just like with Kubernetes, one datacenter -must be the [primary](/docs/k8s/deployment-configurations/multi-cluster/kubernetes#primary-datacenter). +must be the [primary](/consul/docs/k8s/deployment-configurations/multi-cluster/kubernetes#primary-datacenter). ## Kubernetes as the Primary If your primary datacenter is running on Kubernetes, use the Helm config from the -[Primary Datacenter](/docs/k8s/deployment-configurations/multi-cluster/kubernetes#primary-datacenter) section to install Consul. +[Primary Datacenter](/consul/docs/k8s/deployment-configurations/multi-cluster/kubernetes#primary-datacenter) section to install Consul. -Once installed on Kubernetes, and with the `ProxyDefaults` [resource created](/docs/k8s/deployment-configurations/multi-cluster/kubernetes#proxydefaults), +Once installed on Kubernetes, and with the `ProxyDefaults` [resource created](/consul/docs/k8s/deployment-configurations/multi-cluster/kubernetes#proxydefaults), you'll need to export the following information from the primary Kubernetes cluster: - Certificate authority cert and key (in order to create SSL certs for VMs) @@ -63,7 +63,7 @@ The following sections detail how to export this data. ==> Saved vm-dc-server-consul-0-key.pem ``` - -> Note the `-node` option in the above command. This should be same as the node name of the [Consul Agent](/docs/agent#running-an-agent). This is a [requirement](/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways#tls) for Consul Federation to work. Alternatively, if you plan to use the same certificate and key pair on all your Consul server nodes, or you don't know the nodename in advance, use `-node "*"` instead. + -> Note the `-node` option in the above command. This should be same as the node name of the [Consul Agent](/consul/docs/agent#running-an-agent). This is a [requirement](/consul/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways#tls) for Consul Federation to work. Alternatively, if you plan to use the same certificate and key pair on all your Consul server nodes, or you don't know the nodename in advance, use `-node "*"` instead. Not satisfying this requirement would result in the following error in the Consul Server logs: `[ERROR] agent.server.rpc: TLS handshake failed: conn=from= error="remote error: tls: bad certificate"` @@ -95,7 +95,7 @@ The following sections detail how to export this data. ==> Saved dc1-client-consul-0-key.pem ``` - Or use the [auto_encrypt](/docs/agent/config/config-files#auto_encrypt) feature. + Or use the [auto_encrypt](/consul/docs/agent/config/config-files#auto_encrypt) feature. ### Mesh Gateway Addresses @@ -144,7 +144,7 @@ acls { ``` -> **NOTE:** You'll also need to set up additional ACL tokens as needed by the -ACL system. See tutorial [Secure Consul with Access Control Lists (ACLs)](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production#apply-individual-tokens-to-agents) +ACL system. See tutorial [Secure Consul with Access Control Lists (ACLs)](/consul/tutorials/security/access-control-setup-production#apply-individual-tokens-to-agents) for more information. ### Gossip Encryption Key @@ -209,11 +209,11 @@ ports { ## Kubernetes as the Secondary If you're running your primary datacenter on VMs then you'll need to manually -construct the [Federation Secret](/docs/k8s/deployment-configurations/multi-cluster/kubernetes#federation-secret) in order to federate +construct the [Federation Secret](/consul/docs/k8s/deployment-configurations/multi-cluster/kubernetes#federation-secret) in order to federate Kubernetes clusters as secondaries. -> Your VM cluster must be running mesh gateways, and have mesh gateway WAN -federation enabled. See [WAN Federation via Mesh Gateways](/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways). +federation enabled. See [WAN Federation via Mesh Gateways](/consul/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways). You'll need: @@ -321,7 +321,7 @@ kubectl create secret generic consul-federation \ If ACLs are enabled, you must next determine the Kubernetes API URL for the secondary cluster. The API URL of the must be specified in the config files for all secondary clusters because secondary clusters need to create global Consul ACL tokens (tokens that are valid in all datacenters) and these tokens can only be created -by the primary datacenter. By setting the API URL, the secondary cluster will configure a [Consul auth method](/docs/security/acl/auth-methods) +by the primary datacenter. By setting the API URL, the secondary cluster will configure a [Consul auth method](/consul/docs/security/acl/auth-methods) in the primary cluster so that components in the secondary cluster can use their Kubernetes ServiceAccount tokens to retrieve global Consul ACL tokens from the primary. @@ -390,14 +390,14 @@ gateways running on VMs. 1. Set `global.federation.k8sAuthMethodHost` to the Kubernetes API URL of this cluster (including `https://`). 1. `global.federation.primaryDatacenter` should be set to the name of your primary datacenter. -With your config file ready to go, follow our [Installation Guide](/docs/k8s/installation/install) +With your config file ready to go, follow our [Installation Guide](/consul/docs/k8s/installation/install) to install Consul on your secondary cluster(s). After installation, if you're using consul-helm 0.30.0+, [create the -`ProxyDefaults` resource](/docs/k8s/deployment-configurations/multi-cluster/kubernetes#proxydefaults) +`ProxyDefaults` resource](/consul/docs/k8s/deployment-configurations/multi-cluster/kubernetes#proxydefaults) to allow traffic between datacenters. ## Next Steps -In both cases (Kubernetes as primary or secondary), after installation, follow the [Verifying Federation](/docs/k8s/deployment-configurations/multi-cluster/kubernetes#verifying-federation) +In both cases (Kubernetes as primary or secondary), after installation, follow the [Verifying Federation](/consul/docs/k8s/deployment-configurations/multi-cluster/kubernetes#verifying-federation) section to verify that federation is working as expected. diff --git a/website/content/docs/k8s/deployment-configurations/servers-outside-kubernetes.mdx b/website/content/docs/k8s/deployment-configurations/servers-outside-kubernetes.mdx index 0a5afc9ffb..93c98d7f31 100644 --- a/website/content/docs/k8s/deployment-configurations/servers-outside-kubernetes.mdx +++ b/website/content/docs/k8s/deployment-configurations/servers-outside-kubernetes.mdx @@ -23,7 +23,7 @@ The `externalServers.hosts` value must be provided and should be set to a DNS, a or an `exec=` string with a command returning Consul IPs. Please see [this documentation](https://github.com/hashicorp/go-netaddrs) on how the `exec=` string works. Other values in the `externalServers` section are optional. Please refer to -[Helm Chart configuration](https://developer.hashicorp.com/consul/docs/k8s/helm#h-externalservers) for more details. +[Helm Chart configuration](/consul/docs/k8s/helm#h-externalservers) for more details. @@ -38,14 +38,14 @@ externalServers: **Note:** To join Consul on Kubernetes to an existing Consul server cluster running outside of Kubernetes, -refer to [Consul servers outside of Kubernetes](/docs/k8s/deployment-configurations/servers-outside-kubernetes). +refer to [Consul servers outside of Kubernetes](/consul/docs/k8s/deployment-configurations/servers-outside-kubernetes). ## Configuring TLS -> **Note:** Consul on Kubernetes currently does not support external servers that require mutual authentication for the HTTPS clients of the Consul servers, that is when servers have either `tls.defaults.verify_incoming` or `tls.https.verify_incoming` set to `true`. -As noted in the [Security Model](/docs/security#secure-configuration), +As noted in the [Security Model](/consul/docs/security#secure-configuration), that setting isn't strictly necessary to support Consul's threat model as it is recommended that all requests contain a valid ACL token. @@ -77,7 +77,7 @@ to help initialize ACL tokens for Consul clients and consul-k8s components for y ### Manually Bootstrapping ACLs -If you would like to call the [ACL bootstrapping API](/api-docs/acl#bootstrap-acls) yourself or if your cluster has already been bootstrapped with ACLs, +If you would like to call the [ACL bootstrapping API](/consul/api-docs/acl#bootstrap-acls) yourself or if your cluster has already been bootstrapped with ACLs, you can provide the bootstrap token to the Helm chart. The Helm chart will then use this token to configure ACLs for Consul clients and any consul-k8s components you are enabling. @@ -109,9 +109,9 @@ The bootstrap token requires the following minimal permissions: - `agent:read` if using WAN federation over mesh gateways Next, configure external servers. The Helm chart will use this configuration to talk to the Consul server's API -to create policies, tokens, and an auth method. If you are [enabling Consul Connect](/docs/k8s/connect), +to create policies, tokens, and an auth method. If you are [enabling Consul Connect](/consul/docs/k8s/connect), `k8sAuthMethodHost` should be set to the address of your Kubernetes API server -so that the Consul servers can validate a Kubernetes service account token when using the [Kubernetes auth method](/docs/security/acl/auth-methods/kubernetes) +so that the Consul servers can validate a Kubernetes service account token when using the [Kubernetes auth method](/consul/docs/security/acl/auth-methods/kubernetes) with `consul login`. diff --git a/website/content/docs/k8s/deployment-configurations/single-dc-multi-k8s.mdx b/website/content/docs/k8s/deployment-configurations/single-dc-multi-k8s.mdx index eff21714dd..b9694b3912 100644 --- a/website/content/docs/k8s/deployment-configurations/single-dc-multi-k8s.mdx +++ b/website/content/docs/k8s/deployment-configurations/single-dc-multi-k8s.mdx @@ -7,7 +7,7 @@ description: >- # Deploy Single Consul Datacenter Across Multiple Kubernetes Clusters -~> **Note:** When running Consul across multiple Kubernetes clusters, we recommend using [admin partitions](/docs/enterprise/admin-partitions) for production environments. This Consul Enterprise feature allows you to accommodate multiple tenants without resource collisions when administering a cluster at scale. Admin partitions also enable you to run Consul on Kubernetes clusters across a non-flat network. +~> **Note:** When running Consul across multiple Kubernetes clusters, we recommend using [admin partitions](/consul/docs/enterprise/admin-partitions) for production environments. This Consul Enterprise feature allows you to accommodate multiple tenants without resource collisions when administering a cluster at scale. Admin partitions also enable you to run Consul on Kubernetes clusters across a non-flat network. This page describes deploying a single Consul datacenter in multiple Kubernetes clusters, with servers running in one cluster and only Consul on Kubernetes components in the rest of the clusters. @@ -172,7 +172,7 @@ $ helm install ${HELM_RELEASE_CONSUL} --values cluster2-values.yaml hashicorp/co ## Verifying the Consul Service Mesh works -~> When Transparent proxy is enabled, services in one Kubernetes cluster that need to communicate with a service in another Kubernetes cluster must have an explicit upstream configured through the ["consul.hashicorp.com/connect-service-upstreams"](/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) annotation. +~> When Transparent proxy is enabled, services in one Kubernetes cluster that need to communicate with a service in another Kubernetes cluster must have an explicit upstream configured through the ["consul.hashicorp.com/connect-service-upstreams"](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) annotation. Now that the Consul cluster spanning across multiple k8s clusters is up and running, deploy two services in separate k8s clusters and verify that they can connect to each other. diff --git a/website/content/docs/k8s/deployment-configurations/vault/data-integration/bootstrap-token.mdx b/website/content/docs/k8s/deployment-configurations/vault/data-integration/bootstrap-token.mdx index 666de84610..582f781c23 100644 --- a/website/content/docs/k8s/deployment-configurations/vault/data-integration/bootstrap-token.mdx +++ b/website/content/docs/k8s/deployment-configurations/vault/data-integration/bootstrap-token.mdx @@ -9,7 +9,7 @@ description: >- This topic describes how to configure the Consul Helm chart to use an ACL bootstrap token stored in Vault. ## Overview -To use an ACL bootstrap token stored in Vault, follow the steps outlined in the [Data Integration](/docs/k8s/deployment-configurations/vault/data-integration) section. +To use an ACL bootstrap token stored in Vault, follow the steps outlined in the [Data Integration](/consul/docs/k8s/deployment-configurations/vault/data-integration) section. Complete the following steps once: 1. Store the secret in Vault. @@ -21,8 +21,8 @@ Repeat the following steps for each datacenter in the cluster: ## Prerequisites Prior to setting up the data integration between Vault and Consul on Kubernetes, you will need to have: -1. Read and completed the steps in the [Systems Integration](/docs/k8s/deployment-configurations/vault/systems-integration) section of [Vault as a Secrets Backend](/docs/k8s/deployment-configurations/vault). -2. Read the [Data Integration Overview](/docs/k8s/deployment-configurations/vault/data-integration) section of [Vault as a Secrets Backend](/docs/k8s/deployment-configurations/vault). +1. Read and completed the steps in the [Systems Integration](/consul/docs/k8s/deployment-configurations/vault/systems-integration) section of [Vault as a Secrets Backend](/consul/docs/k8s/deployment-configurations/vault). +2. Read the [Data Integration Overview](/consul/docs/k8s/deployment-configurations/vault/data-integration) section of [Vault as a Secrets Backend](/consul/docs/k8s/deployment-configurations/vault). ## Store the Secret in Vault diff --git a/website/content/docs/k8s/deployment-configurations/vault/data-integration/connect-ca.mdx b/website/content/docs/k8s/deployment-configurations/vault/data-integration/connect-ca.mdx index 39dda90234..9cc6af4136 100644 --- a/website/content/docs/k8s/deployment-configurations/vault/data-integration/connect-ca.mdx +++ b/website/content/docs/k8s/deployment-configurations/vault/data-integration/connect-ca.mdx @@ -17,7 +17,7 @@ This allows for automatic token rotation once the renewal is no longer possible. ## Overview -To use Vault as the service mesh certificate provider on Kubernetes, you will complete a modified version of the steps outlined in the [Data Integration](/docs/k8s/deployment-configurations/vault/data-integration) section. +To use Vault as the service mesh certificate provider on Kubernetes, you will complete a modified version of the steps outlined in the [Data Integration](/consul/docs/k8s/deployment-configurations/vault/data-integration) section. Complete the following steps once: 1. Create a Vault policy that authorizes the desired level of access to the secret. @@ -28,14 +28,14 @@ Repeat the following steps for each datacenter in the cluster: ## Prerequisites Prior to setting up the data integration between Vault and Consul on Kubernetes, you will need to have: -1. Read and completed the steps in the [Systems Integration](/docs/k8s/deployment-configurations/vault/systems-integration) section of [Vault as a Secrets Backend](/docs/k8s/deployment-configurations/vault). -2. Read the [Data Integration Overview](/docs/k8s/deployment-configurations/vault/data-integration) section of [Vault as a Secrets Backend](/docs/k8s/deployment-configurations/vault). +1. Read and completed the steps in the [Systems Integration](/consul/docs/k8s/deployment-configurations/vault/systems-integration) section of [Vault as a Secrets Backend](/consul/docs/k8s/deployment-configurations/vault). +2. Read the [Data Integration Overview](/consul/docs/k8s/deployment-configurations/vault/data-integration) section of [Vault as a Secrets Backend](/consul/docs/k8s/deployment-configurations/vault). ## Create Vault policy -To configure [Vault as the provider](/docs/connect/ca/vault) for the Consul service mesh certificates, +To configure [Vault as the provider](/consul/docs/connect/ca/vault) for the Consul service mesh certificates, you will first need to decide on the type of policy that is suitable for you. -To see the permissions that Consul would need in Vault, please see [Vault ACL policies](/docs/connect/ca/vault#vault-acl-policies) +To see the permissions that Consul would need in Vault, please see [Vault ACL policies](/consul/docs/connect/ca/vault#vault-acl-policies) documentation. ## Create Vault Authorization Roles for Consul @@ -84,7 +84,7 @@ The `address` you provide to the `connectCA` configuration can be a Kubernetes D address if the Vault cluster is running the same Kubernetes cluster. The `rootPKIPath` and `intermediatePKIPath` should be the same as the ones defined in your Connect CA policy. Behind the scenes, Consul will authenticate to Vault using a Kubernetes -service account using the [Kubernetes auth method](https://www.vaultproject.io/docs/auth/kubernetes) and will use the Vault token for any API calls to Vault. If the Vault token can not be renewed, Consul will re-authenticate to +service account using the [Kubernetes auth method](/vault/docs/auth/kubernetes) and will use the Vault token for any API calls to Vault. If the Vault token can not be renewed, Consul will re-authenticate to generate a new Vault token. The `vaultCASecret` is the Kubernetes secret that stores the CA Certificate that is used for Vault communication. To provide a CA, you first need to create a Kubernetes secret containing the CA. For example, you may create a secret with the Vault CA like so: diff --git a/website/content/docs/k8s/deployment-configurations/vault/data-integration/enterprise-license.mdx b/website/content/docs/k8s/deployment-configurations/vault/data-integration/enterprise-license.mdx index c086c03bfd..ef3ab8eaaf 100644 --- a/website/content/docs/k8s/deployment-configurations/vault/data-integration/enterprise-license.mdx +++ b/website/content/docs/k8s/deployment-configurations/vault/data-integration/enterprise-license.mdx @@ -9,7 +9,7 @@ description: >- This topic describes how to configure the Consul Helm chart to use an enterprise license stored in Vault. ## Overview -Complete the steps outlined in the [Data Integration](/docs/k8s/deployment-configurations/vault/data-integration) section to use an enterprise license stored in Vault. +Complete the steps outlined in the [Data Integration](/consul/docs/k8s/deployment-configurations/vault/data-integration) section to use an enterprise license stored in Vault. Complete the following steps once: 1. Store the secret in Vault. @@ -21,8 +21,8 @@ Repeat the following steps for each datacenter in the cluster: ## Prerequisites Prior to setting up the data integration between Vault and Consul on Kubernetes, you will need to have: -1. Read and completed the steps in the [Systems Integration](/docs/k8s/deployment-configurations/vault/systems-integration) section of [Vault as a Secrets Backend](/docs/k8s/deployment-configurations/vault). -2. Read the [Data Integration Overview](/docs/k8s/deployment-configurations/vault/data-integration) section of [Vault as a Secrets Backend](/docs/k8s/deployment-configurations/vault). +1. Read and completed the steps in the [Systems Integration](/consul/docs/k8s/deployment-configurations/vault/systems-integration) section of [Vault as a Secrets Backend](/consul/docs/k8s/deployment-configurations/vault). +2. Read the [Data Integration Overview](/consul/docs/k8s/deployment-configurations/vault/data-integration) section of [Vault as a Secrets Backend](/consul/docs/k8s/deployment-configurations/vault). ## Store the Secret in Vault diff --git a/website/content/docs/k8s/deployment-configurations/vault/data-integration/gossip.mdx b/website/content/docs/k8s/deployment-configurations/vault/data-integration/gossip.mdx index dd2915ba52..186ae3f7dc 100644 --- a/website/content/docs/k8s/deployment-configurations/vault/data-integration/gossip.mdx +++ b/website/content/docs/k8s/deployment-configurations/vault/data-integration/gossip.mdx @@ -10,7 +10,7 @@ description: >- This topic describes how to configure the Consul Helm chart to use a gossip encryption key stored in Vault. ## Overview -Complete the steps outlined in the [Data Integration](/docs/k8s/deployment-configurations/vault/data-integration) section to use a gossip encryption key stored in Vault. +Complete the steps outlined in the [Data Integration](/consul/docs/k8s/deployment-configurations/vault/data-integration) section to use a gossip encryption key stored in Vault. Complete the following steps once: 1. Store the secret in Vault. @@ -22,8 +22,8 @@ Repeat the following steps for each datacenter in the cluster: ## Prerequisites Prior to setting up the data integration between Vault and Consul on Kubernetes, you will need to have: -1. Read and completed the steps in the [Systems Integration](/docs/k8s/deployment-configurations/vault/systems-integration) section of [Vault as a Secrets Backend](/docs/k8s/deployment-configurations/vault). -2. Read the [Data Integration Overview](/docs/k8s/deployment-configurations/vault/data-integration) section of [Vault as a Secrets Backend](/docs/k8s/deployment-configurations/vault). +1. Read and completed the steps in the [Systems Integration](/consul/docs/k8s/deployment-configurations/vault/systems-integration) section of [Vault as a Secrets Backend](/consul/docs/k8s/deployment-configurations/vault). +2. Read the [Data Integration Overview](/consul/docs/k8s/deployment-configurations/vault/data-integration) section of [Vault as a Secrets Backend](/consul/docs/k8s/deployment-configurations/vault). ## Store the Secret in Vault First, generate and store the gossip key in Vault. You will only need to perform this action once: diff --git a/website/content/docs/k8s/deployment-configurations/vault/data-integration/index.mdx b/website/content/docs/k8s/deployment-configurations/vault/data-integration/index.mdx index fb0584a633..2ce631b9ce 100644 --- a/website/content/docs/k8s/deployment-configurations/vault/data-integration/index.mdx +++ b/website/content/docs/k8s/deployment-configurations/vault/data-integration/index.mdx @@ -11,7 +11,7 @@ This topic describes how to configure Vault and Consul in order to share secrets ## Prerequisites -Before you set up the data integration between Vault and Consul on Kubernetes, read and complete the steps in the [Systems Integration](/docs/k8s/deployment-configurations/vault/systems-integration) section of [Vault as a Secrets Backend](/docs/k8s/deployment-configurations/vault). +Before you set up the data integration between Vault and Consul on Kubernetes, read and complete the steps in the [Systems Integration](/consul/docs/k8s/deployment-configurations/vault/systems-integration) section of [Vault as a Secrets Backend](/consul/docs/k8s/deployment-configurations/vault). ## General integration steps @@ -37,15 +37,15 @@ It includes things like terminating gateways, ingress gateways, etc.) | Secret | Service Account For | Configurable Role in Consul k8s Helm | | ------ | ------------------- | ------------------------------------ | -|[ACL Bootstrap token](/docs/k8s/deployment-configurations/vault/data-integration/bootstrap-token) | Consul server-acl-init job | [`global.secretsBackend.vault.manageSystemACLsRole`](/docs/k8s/helm#v-global-secretsbackend-vault-managesystemaclsrole)| -|[ACL Partition token](/docs/k8s/deployment-configurations/vault/data-integration/partition-token) | Consul server-acl-init job | [`global.secretsBackend.vault.manageSystemACLsRole`](/docs/k8s/helm#v-global-secretsbackend-vault-managesystemaclsrole)| -|[ACL Replication token](/docs/k8s/deployment-configurations/vault/data-integration/replication-token) | Consul server-acl-init job | [`global.secretsBackend.vault.manageSystemACLsRole`](/docs/k8s/helm#v-global-secretsbackend-vault-managesystemaclsrole)| -|[Enterprise license](/docs/k8s/deployment-configurations/vault/data-integration/enterprise-license) | Consul servers
    Consul clients | [`global.secretsBackend.vault.consulServerRole`](/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)
    [`global.secretsBackend.vault.consulClientRole`](/docs/k8s/helm#v-global-secretsbackend-vault-consulclientrole)| -|[Gossip encryption key](/docs/k8s/deployment-configurations/vault/data-integration/gossip) | Consul servers
    Consul clients | [`global.secretsBackend.vault.consulServerRole`](/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)
    [`global.secretsBackend.vault.consulClientRole`](/docs/k8s/helm#v-global-secretsbackend-vault-consulclientrole)| -|[Snapshot Agent config](/docs/k8s/deployment-configurations/vault/data-integration/snapshot-agent-config) | Consul servers | [`global.secretsBackend.vault.consulServerRole`](/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)| -|[Server TLS credentials](/docs/k8s/deployment-configurations/vault/data-integration/server-tls) | Consul servers
    Consul clients
    Consul components | [`global.secretsBackend.vault.consulServerRole`](/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)
    [`global.secretsBackend.vault.consulClientRole`](/docs/k8s/helm#v-global-secretsbackend-vault-consulclientrole)
    [`global.secretsBackend.vault.consulCARole`](/docs/k8s/helm#v-global-secretsbackend-vault-consulcarole)| -|[Service Mesh and Consul client TLS credentials](/docs/k8s/deployment-configurations/vault/data-integration/connect-ca) | Consul servers | [`global.secretsBackend.vault.consulServerRole`](/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)| -|[Webhook TLS certificates for controller and connect inject](/docs/k8s/deployment-configurations/vault/data-integration/connect-ca) | Consul controllers
    Consul connect inject | [`global.secretsBackend.vault.controllerRole`](/docs/k8s/helm#v-global-secretsbackend-vault-controllerrole)
    [`global.secretsBackend.vault.connectInjectRole`](/docs/k8s/helm#v-global-secretsbackend-vault-controllerrole)| +|[ACL Bootstrap token](/consul/docs/k8s/deployment-configurations/vault/data-integration/bootstrap-token) | Consul server-acl-init job | [`global.secretsBackend.vault.manageSystemACLsRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-managesystemaclsrole)| +|[ACL Partition token](/consul/docs/k8s/deployment-configurations/vault/data-integration/partition-token) | Consul server-acl-init job | [`global.secretsBackend.vault.manageSystemACLsRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-managesystemaclsrole)| +|[ACL Replication token](/consul/docs/k8s/deployment-configurations/vault/data-integration/replication-token) | Consul server-acl-init job | [`global.secretsBackend.vault.manageSystemACLsRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-managesystemaclsrole)| +|[Enterprise license](/consul/docs/k8s/deployment-configurations/vault/data-integration/enterprise-license) | Consul servers
    Consul clients | [`global.secretsBackend.vault.consulServerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)
    [`global.secretsBackend.vault.consulClientRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulclientrole)| +|[Gossip encryption key](/consul/docs/k8s/deployment-configurations/vault/data-integration/gossip) | Consul servers
    Consul clients | [`global.secretsBackend.vault.consulServerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)
    [`global.secretsBackend.vault.consulClientRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulclientrole)| +|[Snapshot Agent config](/consul/docs/k8s/deployment-configurations/vault/data-integration/snapshot-agent-config) | Consul servers | [`global.secretsBackend.vault.consulServerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)| +|[Server TLS credentials](/consul/docs/k8s/deployment-configurations/vault/data-integration/server-tls) | Consul servers
    Consul clients
    Consul components | [`global.secretsBackend.vault.consulServerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)
    [`global.secretsBackend.vault.consulClientRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulclientrole)
    [`global.secretsBackend.vault.consulCARole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulcarole)| +|[Service Mesh and Consul client TLS credentials](/consul/docs/k8s/deployment-configurations/vault/data-integration/connect-ca) | Consul servers | [`global.secretsBackend.vault.consulServerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)| +|[Webhook TLS certificates for controller and connect inject](/consul/docs/k8s/deployment-configurations/vault/data-integration/connect-ca) | Consul controllers
    Consul connect inject | [`global.secretsBackend.vault.controllerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-controllerrole)
    [`global.secretsBackend.vault.connectInjectRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-controllerrole)| ### Secondary datacenters @@ -57,20 +57,20 @@ The mapping for secondary data centers is similar with the following differences | Secret | Service Account For | Configurable Role in Consul k8s Helm | | ------ | ------------------- | ------------------------------------ | -|[ACL Partition token](/docs/k8s/deployment-configurations/vault/data-integration/partition-token) | Consul server-acl-init job
    Consul partition-init job | [`global.secretsBackend.vault.manageSystemACLsRole`](/docs/k8s/helm#v-global-secretsbackend-vault-managesystemaclsrole)
    [`global.secretsBackend.vault.adminPartitionsRole`](/docs/k8s/helm#v-global-secretsbackend-vault-adminpartitionsrole)| -|[ACL Replication token](/docs/k8s/deployment-configurations/vault/data-integration/replication-token) | Consul server-acl-init job
    Consul servers | [`global.secretsBackend.vault.manageSystemACLsRole`](/docs/k8s/helm#v-global-secretsbackend-vault-managesystemaclsrole)
    [`global.secretsBackend.vault.consulServerRole`](/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)| -|[Enterprise license](/docs/k8s/deployment-configurations/vault/data-integration/enterprise-license) | Consul servers
    Consul clients | [`global.secretsBackend.vault.consulServerRole`](/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)
    [`global.secretsBackend.vault.consulClientRole`](/docs/k8s/helm#v-global-secretsbackend-vault-consulclientrole)| -|[Gossip encryption key](/docs/k8s/deployment-configurations/vault/data-integration/gossip) | Consul servers
    Consul clients | [`global.secretsBackend.vault.consulServerRole`](/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)
    [`global.secretsBackend.vault.consulClientRole`](/docs/k8s/helm#v-global-secretsbackend-vault-consulclientrole)| -|[Snapshot Agent config](/docs/k8s/deployment-configurations/vault/data-integration/snapshot-agent-config) | Consul servers | [`global.secretsBackend.vault.consulServerRole`](/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)| -|[Server TLS credentials](/docs/k8s/deployment-configurations/vault/data-integration/server-tls) | Consul servers
    Consul clients
    Consul components | [`global.secretsBackend.vault.consulServerRole`](/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)
    [`global.secretsBackend.vault.consulClientRole`](/docs/k8s/helm#v-global-secretsbackend-vault-consulclientrole)
    [`global.secretsBackend.vault.consulCARole`](/docs/k8s/helm#v-global-secretsbackend-vault-consulcarole)| -|[Service Mesh and Consul client TLS credentials](/docs/k8s/deployment-configurations/vault/data-integration/connect-ca) | Consul servers | [`global.secretsBackend.vault.consulServerRole`](/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)| -|[Webhook TLS certificates for controller and connect inject](/docs/k8s/deployment-configurations/vault/data-integration/connect-ca) | Consul controllers
    Consul connect inject | [`global.secretsBackend.vault.controllerRole`](/docs/k8s/helm#v-global-secretsbackend-vault-controllerrole)
    [`global.secretsBackend.vault.connectInjectRole`](/docs/k8s/helm#v-global-secretsbackend-vault-controllerrole)| +|[ACL Partition token](/consul/docs/k8s/deployment-configurations/vault/data-integration/partition-token) | Consul server-acl-init job
    Consul partition-init job | [`global.secretsBackend.vault.manageSystemACLsRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-managesystemaclsrole)
    [`global.secretsBackend.vault.adminPartitionsRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-adminpartitionsrole)| +|[ACL Replication token](/consul/docs/k8s/deployment-configurations/vault/data-integration/replication-token) | Consul server-acl-init job
    Consul servers | [`global.secretsBackend.vault.manageSystemACLsRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-managesystemaclsrole)
    [`global.secretsBackend.vault.consulServerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)| +|[Enterprise license](/consul/docs/k8s/deployment-configurations/vault/data-integration/enterprise-license) | Consul servers
    Consul clients | [`global.secretsBackend.vault.consulServerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)
    [`global.secretsBackend.vault.consulClientRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulclientrole)| +|[Gossip encryption key](/consul/docs/k8s/deployment-configurations/vault/data-integration/gossip) | Consul servers
    Consul clients | [`global.secretsBackend.vault.consulServerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)
    [`global.secretsBackend.vault.consulClientRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulclientrole)| +|[Snapshot Agent config](/consul/docs/k8s/deployment-configurations/vault/data-integration/snapshot-agent-config) | Consul servers | [`global.secretsBackend.vault.consulServerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)| +|[Server TLS credentials](/consul/docs/k8s/deployment-configurations/vault/data-integration/server-tls) | Consul servers
    Consul clients
    Consul components | [`global.secretsBackend.vault.consulServerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)
    [`global.secretsBackend.vault.consulClientRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulclientrole)
    [`global.secretsBackend.vault.consulCARole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulcarole)| +|[Service Mesh and Consul client TLS credentials](/consul/docs/k8s/deployment-configurations/vault/data-integration/connect-ca) | Consul servers | [`global.secretsBackend.vault.consulServerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-consulserverrole)| +|[Webhook TLS certificates for controller and connect inject](/consul/docs/k8s/deployment-configurations/vault/data-integration/connect-ca) | Consul controllers
    Consul connect inject | [`global.secretsBackend.vault.controllerRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-controllerrole)
    [`global.secretsBackend.vault.connectInjectRole`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-controllerrole)| ### Combining policies within roles Depending upon your needs, a Consul on Kubernetes service account may need to request more than one secret. To request multiple secrets, create one role for the Consul on Kubernetes service account that is mapped to multiple policies associated with the required secrets. -For example, if your Consul on Kubernetes servers need access to [Consul Server TLS credentials](/docs/k8s/deployment-configurations/vault/data-integration/server-tls) and an [Enterprise license](/docs/k8s/deployment-configurations/vault/data-integration/enterprise-license): +For example, if your Consul on Kubernetes servers need access to [Consul Server TLS credentials](/consul/docs/k8s/deployment-configurations/vault/data-integration/server-tls) and an [Enterprise license](/consul/docs/k8s/deployment-configurations/vault/data-integration/enterprise-license): 1. Create a policy for each secret. @@ -119,18 +119,18 @@ For example, if your Consul on Kubernetes servers need access to [Consul Server The following secrets can be stored in Vault KV secrets engine, which is meant to handle arbitrary secrets: -- [ACL Bootstrap token](/docs/k8s/deployment-configurations/vault/data-integration/bootstrap-token) -- [ACL Partition token](/docs/k8s/deployment-configurations/vault/data-integration/partition-token) -- [ACL Replication token](/docs/k8s/deployment-configurations/vault/data-integration/replication-token) -- [Enterprise license](/docs/k8s/deployment-configurations/vault/data-integration/enterprise-license) -- [Gossip encryption key](/docs/k8s/deployment-configurations/vault/data-integration/gossip) -- [Snapshot Agent config](/docs/k8s/deployment-configurations/vault/data-integration/snapshot-agent-config) +- [ACL Bootstrap token](/consul/docs/k8s/deployment-configurations/vault/data-integration/bootstrap-token) +- [ACL Partition token](/consul/docs/k8s/deployment-configurations/vault/data-integration/partition-token) +- [ACL Replication token](/consul/docs/k8s/deployment-configurations/vault/data-integration/replication-token) +- [Enterprise license](/consul/docs/k8s/deployment-configurations/vault/data-integration/enterprise-license) +- [Gossip encryption key](/consul/docs/k8s/deployment-configurations/vault/data-integration/gossip) +- [Snapshot Agent config](/consul/docs/k8s/deployment-configurations/vault/data-integration/snapshot-agent-config) The following TLS certificates and keys can generated and managed by Vault the Vault PKI Engine, which is meant to handle things like certificate expiration and rotation: -- [Server TLS credentials](/docs/k8s/deployment-configurations/vault/data-integration/server-tls) -- [Service Mesh and Consul client TLS credentials](/docs/k8s/deployment-configurations/vault/data-integration/connect-ca) -- [Vault as the Webhook Certificate Provider for Consul Controller and Connect Inject on Kubernetes](/docs/k8s/deployment-configurations/vault/data-integration/webhook-certs) +- [Server TLS credentials](/consul/docs/k8s/deployment-configurations/vault/data-integration/server-tls) +- [Service Mesh and Consul client TLS credentials](/consul/docs/k8s/deployment-configurations/vault/data-integration/connect-ca) +- [Vault as the Webhook Certificate Provider for Consul Controller and Connect Inject on Kubernetes](/consul/docs/k8s/deployment-configurations/vault/data-integration/webhook-certs) ## Secrets-to-service account mapping diff --git a/website/content/docs/k8s/deployment-configurations/vault/data-integration/partition-token.mdx b/website/content/docs/k8s/deployment-configurations/vault/data-integration/partition-token.mdx index a299f0ea3c..b646a6f803 100644 --- a/website/content/docs/k8s/deployment-configurations/vault/data-integration/partition-token.mdx +++ b/website/content/docs/k8s/deployment-configurations/vault/data-integration/partition-token.mdx @@ -7,10 +7,10 @@ description: >- # Storing the ACL Partition Token in Vault -This topic describes how to configure the Consul Helm chart to use an ACL partition token stored in Vault when using [Admin Partitions](/docs/enterprise/admin-partitions) in Consul Enterprise. +This topic describes how to configure the Consul Helm chart to use an ACL partition token stored in Vault when using [Admin Partitions](/consul/docs/enterprise/admin-partitions) in Consul Enterprise. ## Overview -Complete the steps outlined in the [Data Integration](/docs/k8s/deployment-configurations/vault/data-integration) section to use an ACL partition token stored in Vault. +Complete the steps outlined in the [Data Integration](/consul/docs/k8s/deployment-configurations/vault/data-integration) section to use an ACL partition token stored in Vault. Complete the following steps once: 1. Store the secret in Vault. @@ -22,8 +22,8 @@ Repeat the following steps for each datacenter in the cluster: ## Prerequisites Prior to setting up the data integration between Vault and Consul on Kubernetes, you will need to have: -1. Read and completed the steps in the [Systems Integration](/docs/k8s/deployment-configurations/vault/systems-integration) section of [Vault as a Secrets Backend](/docs/k8s/deployment-configurations/vault). -2. Read the [Data Integration Overview](/docs/k8s/deployment-configurations/vault/data-integration) section of [Vault as a Secrets Backend](/docs/k8s/deployment-configurations/vault). +1. Read and completed the steps in the [Systems Integration](/consul/docs/k8s/deployment-configurations/vault/systems-integration) section of [Vault as a Secrets Backend](/consul/docs/k8s/deployment-configurations/vault). +2. Read the [Data Integration Overview](/consul/docs/k8s/deployment-configurations/vault/data-integration) section of [Vault as a Secrets Backend](/consul/docs/k8s/deployment-configurations/vault). ## Store the Secret in Vault diff --git a/website/content/docs/k8s/deployment-configurations/vault/data-integration/replication-token.mdx b/website/content/docs/k8s/deployment-configurations/vault/data-integration/replication-token.mdx index cc0e244bd1..a7f351d54a 100644 --- a/website/content/docs/k8s/deployment-configurations/vault/data-integration/replication-token.mdx +++ b/website/content/docs/k8s/deployment-configurations/vault/data-integration/replication-token.mdx @@ -9,7 +9,7 @@ description: >- This topic describes how to configure the Consul Helm chart to use an ACL replication token stored in Vault. ## Overview -To use an ACL replication token stored in Vault, follow the steps outlined in the [Data Integration](/docs/k8s/deployment-configurations/vault/data-integration) section. +To use an ACL replication token stored in Vault, follow the steps outlined in the [Data Integration](/consul/docs/k8s/deployment-configurations/vault/data-integration) section. Complete the following steps once: 1. Store the secret in Vault. @@ -21,8 +21,8 @@ Repeat the following steps for each datacenter in the cluster: ## Prerequisites Prior to setting up the data integration between Vault and Consul on Kubernetes, you will need to have: -1. Read and completed the steps in the [Systems Integration](/docs/k8s/deployment-configurations/vault/systems-integration) section of [Vault as a Secrets Backend](/docs/k8s/deployment-configurations/vault). -2. Read the [Data Integration Overview](/docs/k8s/deployment-configurations/vault/data-integration) section of [Vault as a Secrets Backend](/docs/k8s/deployment-configurations/vault). +1. Read and completed the steps in the [Systems Integration](/consul/docs/k8s/deployment-configurations/vault/systems-integration) section of [Vault as a Secrets Backend](/consul/docs/k8s/deployment-configurations/vault). +2. Read the [Data Integration Overview](/consul/docs/k8s/deployment-configurations/vault/data-integration) section of [Vault as a Secrets Backend](/consul/docs/k8s/deployment-configurations/vault). ## Store the Secret in Vault diff --git a/website/content/docs/k8s/deployment-configurations/vault/data-integration/server-tls.mdx b/website/content/docs/k8s/deployment-configurations/vault/data-integration/server-tls.mdx index 02074c48c9..a3b8d82a80 100644 --- a/website/content/docs/k8s/deployment-configurations/vault/data-integration/server-tls.mdx +++ b/website/content/docs/k8s/deployment-configurations/vault/data-integration/server-tls.mdx @@ -8,7 +8,7 @@ description: >- # Vault as the Server TLS Certificate Provider on Kubernetes ## Overview -To use Vault as the server TLS certificate provider on Kubernetes, complete a modified version of the steps outlined in the [Data Integration](/docs/k8s/deployment-configurations/vault/data-integration) section. +To use Vault as the server TLS certificate provider on Kubernetes, complete a modified version of the steps outlined in the [Data Integration](/consul/docs/k8s/deployment-configurations/vault/data-integration) section. Complete the following steps once: 1. Create a Vault policy that authorizes the desired level of access to the secret. @@ -20,8 +20,8 @@ Repeat the following steps for each datacenter in the cluster: ## Prerequisites Prior to setting up the data integration between Vault and Consul on Kubernetes, you will need to have: -1. Read and completed the steps in the [Systems Integration](/docs/k8s/deployment-configurations/vault/systems-integration) section of [Vault as a Secrets Backend](/docs/k8s/deployment-configurations/vault). -2. Read the [Data Integration Overview](/docs/k8s/deployment-configurations/vault/data-integration) section of [Vault as a Secrets Backend](/docs/k8s/deployment-configurations/vault). +1. Read and completed the steps in the [Systems Integration](/consul/docs/k8s/deployment-configurations/vault/systems-integration) section of [Vault as a Secrets Backend](/consul/docs/k8s/deployment-configurations/vault). +2. Read the [Data Integration Overview](/consul/docs/k8s/deployment-configurations/vault/data-integration) section of [Vault as a Secrets Backend](/consul/docs/k8s/deployment-configurations/vault). 3. Complete the [Bootstrapping the PKI Engine](#bootstrapping-the-pki-engine) section. ## Bootstrapping the PKI Engine @@ -54,7 +54,7 @@ TLS certificates to Consul. To use Vault to issue Server TLS certificates, you will need to create the following: 1. Create a policy that allows `["create", "update"]` access to the - [certificate issuing URL](https://www.vaultproject.io/api-docs/secret/pki#generate-certificate) so the Consul servers can + [certificate issuing URL](/vault/api-docs/secret/pki#generate-certificate) so the Consul servers can fetch a new certificate/key pair. The path to the secret referenced in the `path` resource is the same value that you will configure in the `server.serverCert.secretName` Helm configuration (refer to [Update Consul on Kubernetes Helm chart](#update-consul-on-kubernetes-helm-chart)). @@ -75,7 +75,7 @@ To use Vault to issue Server TLS certificates, you will need to create the follo $ vault policy write consul-server consul-server-policy.hcl ``` -1. Create a policy that allows `["read"]` access to the [CA URL](https://www.vaultproject.io/api-docs/secret/pki), +1. Create a policy that allows `["read"]` access to the [CA URL](/vault/api-docs/secret/pki), this is required for the Consul components to communicate with the Consul servers in order to fetch their auto-encryption certificates. The path to the secret referenced in the `path` resource is the same value that you will configure in the `global.tls.caCert.secretName` Helm configuration (refer to [Update Consul on Kubernetes Helm chart](#update-consul-on-kubernetes-helm-chart)). diff --git a/website/content/docs/k8s/deployment-configurations/vault/data-integration/snapshot-agent-config.mdx b/website/content/docs/k8s/deployment-configurations/vault/data-integration/snapshot-agent-config.mdx index 26cbb77c19..235ef68f84 100644 --- a/website/content/docs/k8s/deployment-configurations/vault/data-integration/snapshot-agent-config.mdx +++ b/website/content/docs/k8s/deployment-configurations/vault/data-integration/snapshot-agent-config.mdx @@ -9,7 +9,7 @@ description: >- This topic describes how to configure the Consul Helm chart to use a snapshot agent config stored in Vault. ## Overview -To use an ACL replication token stored in Vault, follow the steps outlined in the [Data Integration](/docs/k8s/deployment-configurations/vault/data-integration) section. +To use an ACL replication token stored in Vault, follow the steps outlined in the [Data Integration](/consul/docs/k8s/deployment-configurations/vault/data-integration) section. Complete the following steps once: 1. Store the secret in Vault. @@ -21,8 +21,8 @@ Repeat the following steps for each datacenter in the cluster: ## Prerequisites Before you set up data integration between Vault and Consul on Kubernetes, complete the following prerequisites: -1. Read and completed the steps in the [Systems Integration](/docs/k8s/deployment-configurations/vault/systems-integration) section of [Vault as a Secrets Backend](/docs/k8s/deployment-configurations/vault). -2. Read the [Data Integration Overview](/docs/k8s/deployment-configurations/vault/data-integration) section of [Vault as a Secrets Backend](/docs/k8s/deployment-configurations/vault). +1. Read and completed the steps in the [Systems Integration](/consul/docs/k8s/deployment-configurations/vault/systems-integration) section of [Vault as a Secrets Backend](/consul/docs/k8s/deployment-configurations/vault). +2. Read the [Data Integration Overview](/consul/docs/k8s/deployment-configurations/vault/data-integration) section of [Vault as a Secrets Backend](/consul/docs/k8s/deployment-configurations/vault). ## Store the Secret in Vault diff --git a/website/content/docs/k8s/deployment-configurations/vault/data-integration/webhook-certs.mdx b/website/content/docs/k8s/deployment-configurations/vault/data-integration/webhook-certs.mdx index a10470729c..aec4fb1d69 100644 --- a/website/content/docs/k8s/deployment-configurations/vault/data-integration/webhook-certs.mdx +++ b/website/content/docs/k8s/deployment-configurations/vault/data-integration/webhook-certs.mdx @@ -19,7 +19,7 @@ When Vault is configured as the controller and connect inject Webhook Certificat - controller and connect inject each locally update its own `mutatingwebhookconfiguration` so that Kubernetes can relay events. - Vault manages certificate rotation and rotates certificates to each webhook. -To use Vault as the controller and connect inject Webhook Certificate Provider, we will need to modify the steps outlined in the [Data Integration](/docs/k8s/deployment-configurations/vault/data-integration) section: +To use Vault as the controller and connect inject Webhook Certificate Provider, we will need to modify the steps outlined in the [Data Integration](/consul/docs/k8s/deployment-configurations/vault/data-integration) section: These following steps will be repeated for each datacenter: 1. Create a Vault policy that authorizes the desired level of access to the secret. @@ -29,10 +29,10 @@ These following steps will be repeated for each datacenter: ## Prerequisites Complete the following prerequisites prior to implementing the integration described in this topic: -1. Verify that you have completed the steps described in [Systems Integration](/docs/k8s/deployment-configurations/vault/systems-integration) section of [Vault as a Secrets Backend](/docs/k8s/deployment-configurations/vault). -1. You should be familiar with the [Data Integration Overview](/docs/k8s/deployment-configurations/vault/data-integration) section of [Vault as a Secrets Backend](/docs/k8s/deployment-configurations/vault). -1. Configure [Vault as the Server TLS Certificate Provider on Kubernetes](/docs/k8s/deployment-configurations/vault/data-integration/server-tls) -1. Configure [Vault as the Service Mesh Certificate Provider on Kubernetes](/docs/k8s/deployment-configurations/vault/data-integration/connect-ca) +1. Verify that you have completed the steps described in [Systems Integration](/consul/docs/k8s/deployment-configurations/vault/systems-integration) section of [Vault as a Secrets Backend](/consul/docs/k8s/deployment-configurations/vault). +1. You should be familiar with the [Data Integration Overview](/consul/docs/k8s/deployment-configurations/vault/data-integration) section of [Vault as a Secrets Backend](/consul/docs/k8s/deployment-configurations/vault). +1. Configure [Vault as the Server TLS Certificate Provider on Kubernetes](/consul/docs/k8s/deployment-configurations/vault/data-integration/server-tls) +1. Configure [Vault as the Service Mesh Certificate Provider on Kubernetes](/consul/docs/k8s/deployment-configurations/vault/data-integration/connect-ca) ## Bootstrapping the PKI Engines Issue the following commands to enable and configure the PKI Secrets Engine to serve TLS certificates for the controller and connect inject webhooks: @@ -72,7 +72,7 @@ Issue the following commands to enable and configure the PKI Secrets Engine to s ``` ## Create Vault Policies 1. Create a policy that allows `["create", "update"]` access to the -[certificate issuing URL](https://www.vaultproject.io/api-docs/secret/pki) so Consul controller and connect inject can fetch a new certificate/key pair and provide it to the Kubernetes `mutatingwebhookconfiguration`. +[certificate issuing URL](/vault/api-docs/secret/pki) so Consul controller and connect inject can fetch a new certificate/key pair and provide it to the Kubernetes `mutatingwebhookconfiguration`. The path to the secret referenced in the `path` resource is the same value that you will configure in the `global.secretsBackend.vault.controller.tlsCert.secretName` and `global.secretsBackend.vault.connectInject.tlsCert.secretName` Helm configuration (refer to [Update Consul on Kubernetes Helm chart](#update-consul-on-kubernetes-helm-chart)). @@ -92,7 +92,7 @@ Issue the following commands to enable and configure the PKI Secrets Engine to s EOF ``` -1. Create a policy that allows `["read"]` access to the [CA URL](https://www.vaultproject.io/api-docs/secret/pki#read-certificate), +1. Create a policy that allows `["read"]` access to the [CA URL](/vault/api-docs/secret/pki#read-certificate), this is required for the Consul components to communicate with the Consul servers in order to fetch their auto-encryption certificates. The path to the secret referenced in the `path` resource is the same values that you will configure in the `global.secretsBackend.vault.controller.caCert.secretName` and `global.secretsBackend.vault.connectInject.caCert.secretName` Helm configuration (refer to [Update Consul on Kubernetes Helm chart](#update-consul-on-kubernetes-helm-chart)). diff --git a/website/content/docs/k8s/deployment-configurations/vault/index.mdx b/website/content/docs/k8s/deployment-configurations/vault/index.mdx index c09b517ead..a3c1f24b7d 100644 --- a/website/content/docs/k8s/deployment-configurations/vault/index.mdx +++ b/website/content/docs/k8s/deployment-configurations/vault/index.mdx @@ -46,9 +46,9 @@ The following TLS certificates and keys can be generated and managed by the Vaul ## Next Steps The Vault integration with Consul on Kubernetes has two aspects or phases: -- [Systems Integration](/docs/k8s/deployment-configurations/vault/systems-integration) - Configure Vault and Consul on Kubernetes systems to leverage Vault as the secrets store. -- [Data Integration](/docs/k8s/deployment-configurations/vault/data-integration) - Configure specific secrets to be stored and +- [Systems Integration](/consul/docs/k8s/deployment-configurations/vault/systems-integration) - Configure Vault and Consul on Kubernetes systems to leverage Vault as the secrets store. +- [Data Integration](/consul/docs/k8s/deployment-configurations/vault/data-integration) - Configure specific secrets to be stored and retrieved from Vault for use with Consul on Kubernetes. -As a next step, please proceed to [Systems Integration](/docs/k8s/deployment-configurations/vault/systems-integration) overview to understand how to first setup Vault and Consul on Kubernetes to leverage Vault as a secrets backend. +As a next step, please proceed to [Systems Integration](/consul/docs/k8s/deployment-configurations/vault/systems-integration) overview to understand how to first setup Vault and Consul on Kubernetes to leverage Vault as a secrets backend. diff --git a/website/content/docs/k8s/deployment-configurations/vault/systems-integration.mdx b/website/content/docs/k8s/deployment-configurations/vault/systems-integration.mdx index 9c50d7df0e..7c4de80bba 100644 --- a/website/content/docs/k8s/deployment-configurations/vault/systems-integration.mdx +++ b/website/content/docs/k8s/deployment-configurations/vault/systems-integration.mdx @@ -12,26 +12,26 @@ Integrating Vault with Consul on Kubernetes includes a one-time setup on Vault a Complete the following steps once: - Enabling Vault KV Secrets Engine - Version 2 to store arbitrary secrets - - Enabling Vault PKI Engine if you are choosing to store and manage either [Consul Server TLS credentials](/docs/k8s/deployment-configurations/vault/data-integration/server-tls) or [Service Mesh and Consul client TLS credentials](/docs/k8s/deployment-configurations/vault/data-integration/connect-ca) + - Enabling Vault PKI Engine if you are choosing to store and manage either [Consul Server TLS credentials](/consul/docs/k8s/deployment-configurations/vault/data-integration/server-tls) or [Service Mesh and Consul client TLS credentials](/consul/docs/k8s/deployment-configurations/vault/data-integration/connect-ca) Repeat the following steps for each datacenter in the cluster: - Installing the Vault Injector within the Consul datacenter installation - Configuring a Kubernetes Auth Method in Vault to authenticate and authorize operations from the Consul datacenter - Enable Vault as the Secrets Backend in the Consul datacenter -Please read [Run Vault on Kubernetes](https://www.vaultproject.io/docs/platform/k8s/helm/run) if instructions on setting up a Vault cluster are needed. +Please read [Run Vault on Kubernetes](/vault/docs/platform/k8s/helm/run) if instructions on setting up a Vault cluster are needed. ## Vault KV Secrets Engine - Version 2 The following secrets can be stored in Vault KV secrets engine, which is meant to handle arbitrary secrets: -- ACL Bootstrap token ([`global.acls.bootstrapToken`](/docs/k8s/helm#v-global-acls-bootstraptoken)) -- ACL Partition token ([`global.acls.partitionToken`](/docs/k8s/helm#v-global-acls-partitiontoken)) -- ACL Replication token ([`global.acls.replicationToken`](/docs/k8s/helm#v-global-acls-replicationtoken)) -- Gossip encryption key ([`global.gossipEncryption`](/docs/k8s/helm#v-global-gossipencryption)) -- Enterprise license ([`global.enterpriseLicense`](/docs/k8s/helm#v-global-enterpriselicense)) -- Snapshot Agent config ([`client.snapshotAgent.configSecret`](/docs/k8s/helm#v-client-snapshotagent-configsecret)) +- ACL Bootstrap token ([`global.acls.bootstrapToken`](/consul/docs/k8s/helm#v-global-acls-bootstraptoken)) +- ACL Partition token ([`global.acls.partitionToken`](/consul/docs/k8s/helm#v-global-acls-partitiontoken)) +- ACL Replication token ([`global.acls.replicationToken`](/consul/docs/k8s/helm#v-global-acls-replicationtoken)) +- Gossip encryption key ([`global.gossipEncryption`](/consul/docs/k8s/helm#v-global-gossipencryption)) +- Enterprise license ([`global.enterpriseLicense`](/consul/docs/k8s/helm#v-global-enterpriselicense)) +- Snapshot Agent config ([`client.snapshotAgent.configSecret`](/consul/docs/k8s/helm#v-client-snapshotagent-configsecret)) -In order to store any of these secrets, we must enable the [Vault KV secrets engine - Version 2](https://www.vaultproject.io/docs/secrets/kv/kv-v2). +In order to store any of these secrets, we must enable the [Vault KV secrets engine - Version 2](/vault/docs/secrets/kv/kv-v2). ```shell-session $ vault secrets enable -path=consul kv-v2 @@ -39,7 +39,7 @@ $ vault secrets enable -path=consul kv-v2 ## Vault PKI Engine -The Vault PKI Engine must be enabled in order to leverage Vault for issuing Consul Server TLS certificates. More details for configuring the PKI Engine is found in [Bootstrapping the PKI Engine](/docs/k8s/deployment-configurations/vault/data-integration/server-tls#bootstrapping-the-pki-engine) under the Server TLS section. +The Vault PKI Engine must be enabled in order to leverage Vault for issuing Consul Server TLS certificates. More details for configuring the PKI Engine is found in [Bootstrapping the PKI Engine](/consul/docs/k8s/deployment-configurations/vault/data-integration/server-tls#bootstrapping-the-pki-engine) under the Server TLS section. ```shell-session $ vault secrets enable pki @@ -100,7 +100,7 @@ Before installing the Vault Injector and configuring the Vault Kubernetes Auth M     - If Vault is not running on Kubernetes, utilize the `api_addr` as defined in the Vault [High Availability Parameters](https://www.vaultproject.io/docs/configuration#high-availability-parameters) configuration: + If Vault is not running on Kubernetes, utilize the `api_addr` as defined in the Vault [High Availability Parameters](/vault/docs/configuration#high-availability-parameters) configuration: ```shell-session $ export VAULT_SERVER_HOST= ``` @@ -112,7 +112,7 @@ Before installing the Vault Injector and configuring the Vault Kubernetes Auth M $ export VAULT_ADDR=http://${VAULT_SERVER_HOST}:8200 ``` - If your vault installation is current exposed using SSL, this address will need to use `https` instead of `http`. You will also need to setup the [`VAULT_CACERT`](https://www.vaultproject.io/docs/commands#vault_cacert) environment variable. + If your vault installation is current exposed using SSL, this address will need to use `https` instead of `http`. You will also need to setup the [`VAULT_CACERT`](/vault/docs/commands#vault_cacert) environment variable. - VAULT_TOKEN @@ -123,7 +123,7 @@ Before installing the Vault Injector and configuring the Vault Kubernetes Auth M ## Install Vault Injector in Consul k8s cluster -A minimal valid installation of Vault Kubernetes must include the Agent Injector which is utilized for accessing secrets from Vault. Vault servers could be deployed external to Vault on Kubernetes with the [`injector.externalVaultAddr`](https://www.vaultproject.io/docs/platform/k8s/helm/configuration#externalvaultaddr) value in the Vault Helm Configuration. +A minimal valid installation of Vault Kubernetes must include the Agent Injector which is utilized for accessing secrets from Vault. Vault servers could be deployed external to Vault on Kubernetes with the [`injector.externalVaultAddr`](/vault/docs/platform/k8s/helm/configuration#externalvaultaddr) value in the Vault Helm Configuration. ```shell-session $ cat <> vault-injector.yaml @@ -153,7 +153,7 @@ Ensure that the Vault Kubernetes Auth method is enabled. $ vault auth enable -path=kubernetes-${DATACENTER} kubernetes ``` -After enabling the Kubernetes auth method, in Vault, ensure that you have configured the Kubernetes Auth method properly as described in [Kubernetes Auth Method Configuration](https://www.vaultproject.io/docs/auth/kubernetes#configuration). +After enabling the Kubernetes auth method, in Vault, ensure that you have configured the Kubernetes Auth method properly as described in [Kubernetes Auth Method Configuration](/vault/docs/auth/kubernetes#configuration). First, while targeting your Consul cluster, get the externally reachable address of the Consul Kubernetes cluster. @@ -175,14 +175,14 @@ $ vault write auth/kubernetes/config \ ## Update Vault Helm chart Finally, you will configure the Consul on Kubernetes helm chart for the datacenter to expect to receive the following values (if you have configured them) to be retrieved from Vault: -- ACL Bootstrap token ([`global.acls.bootstrapToken`](/docs/k8s/helm#v-global-acls-bootstraptoken)) -- ACL Partition token ([`global.acls.partitionToken`](/docs/k8s/helm#v-global-acls-partitiontoken)) -- ACL Replication token ([`global.acls.replicationToken`](/docs/k8s/helm#v-global-acls-replicationtoken)) -- Enterprise license ([`global.enterpriseLicense`](/docs/k8s/helm#v-global-enterpriselicense)) -- Gossip encryption key ([`global.gossipEncryption`](/docs/k8s/helm#v-global-gossipencryption)) -- Snapshot Agent config ([`client.snapshotAgent.configSecret`](/docs/k8s/helm#v-client-snapshotagent-configsecret)) -- TLS CA certificates ([`global.tls.caCert`](/docs/k8s/helm#v-global-tls-cacert)) -- Server TLS certificates ([`server.serverCert`](/docs/k8s/helm#v-server-servercert)) +- ACL Bootstrap token ([`global.acls.bootstrapToken`](/consul/docs/k8s/helm#v-global-acls-bootstraptoken)) +- ACL Partition token ([`global.acls.partitionToken`](/consul/docs/k8s/helm#v-global-acls-partitiontoken)) +- ACL Replication token ([`global.acls.replicationToken`](/consul/docs/k8s/helm#v-global-acls-replicationtoken)) +- Enterprise license ([`global.enterpriseLicense`](/consul/docs/k8s/helm#v-global-enterpriselicense)) +- Gossip encryption key ([`global.gossipEncryption`](/consul/docs/k8s/helm#v-global-gossipencryption)) +- Snapshot Agent config ([`client.snapshotAgent.configSecret`](/consul/docs/k8s/helm#v-client-snapshotagent-configsecret)) +- TLS CA certificates ([`global.tls.caCert`](/consul/docs/k8s/helm#v-global-tls-cacert)) +- Server TLS certificates ([`server.serverCert`](/consul/docs/k8s/helm#v-server-servercert)) @@ -197,7 +197,7 @@ global: ## Next Steps -As a next step, please proceed to Vault integration with Consul on Kubernetes' [Data Integration](/docs/k8s/deployment-configurations/vault/data-integration). +As a next step, please proceed to Vault integration with Consul on Kubernetes' [Data Integration](/consul/docs/k8s/deployment-configurations/vault/data-integration). ## Troubleshooting diff --git a/website/content/docs/k8s/deployment-configurations/vault/wan-federation.mdx b/website/content/docs/k8s/deployment-configurations/vault/wan-federation.mdx index dcaee669bf..5c2badb093 100644 --- a/website/content/docs/k8s/deployment-configurations/vault/wan-federation.mdx +++ b/website/content/docs/k8s/deployment-configurations/vault/wan-federation.mdx @@ -7,12 +7,12 @@ description: >- # Federation Between Kubernetes Clusters with Vault as Secrets Backend -~> **Note**: This topic requires familiarity with [Mesh Gateways](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters), [WAN Federation Via Mesh Gateways](/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways). +~> **Note**: This topic requires familiarity with [Mesh Gateways](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters), [WAN Federation Via Mesh Gateways](/consul/docs/connect/gateways/mesh-gateway/wan-federation-via-mesh-gateways). -This page describes how you can federate multiple Kubernetes clusters using Vault as the secrets backend. See the [Multi-Cluster Overview](/docs/k8s/deployment-configurations/multi-cluster) for more information on use cases and how it works. +This page describes how you can federate multiple Kubernetes clusters using Vault as the secrets backend. See the [Multi-Cluster Overview](/consul/docs/k8s/deployment-configurations/multi-cluster) for more information on use cases and how it works. ## Differences Between Using Kubernetes Secrets vs. Vault -The [Federation Between Kubernetes Clusters](/docs/k8s/deployment-configurations/multi-cluster/kubernetes) page provides an overview of WAN Federation using Mesh Gateways with Kubernetes secrets as the secret backend. When using Vault as the secrets backend, there are different systems and data integration configuration that will be explained in the [Usage](#usage) section of this page. The other main difference is that when using Vault, there is no need for you to export and import a [Federation Secret](/docs/k8s/deployment-configurations/multi-cluster/kubernetes#federation-secret) in each datacenter. +The [Federation Between Kubernetes Clusters](/consul/docs/k8s/deployment-configurations/multi-cluster/kubernetes) page provides an overview of WAN Federation using Mesh Gateways with Kubernetes secrets as the secret backend. When using Vault as the secrets backend, there are different systems and data integration configuration that will be explained in the [Usage](#usage) section of this page. The other main difference is that when using Vault, there is no need for you to export and import a [Federation Secret](/consul/docs/k8s/deployment-configurations/multi-cluster/kubernetes#federation-secret) in each datacenter. ## Usage @@ -28,7 +28,7 @@ The Vault Agents on each Consul pod will communicate directly with Vault on its ![Vault agent and server communication](/img/k8s/consul-vault-wan-federation-vault-communication.svg 'Vault agent and server communication') -The two data centers will federated using mesh gateways. This communication topology is also described in the [WAN Federation Via Mesh Gateways](/docs/k8s/deployment-configurations/multi-cluster#wan-federation-via-mesh-gateways) section of [Multi-Cluster Federation Overview](/docs/k8s/deployment-configurations/multi-cluster). +The two data centers will federated using mesh gateways. This communication topology is also described in the [WAN Federation Via Mesh Gateways](/consul/docs/k8s/deployment-configurations/multi-cluster#wan-federation-via-mesh-gateways) section of [Multi-Cluster Federation Overview](/consul/docs/k8s/deployment-configurations/multi-cluster). ![Mesh Federation via Mesh Gateways](/img/k8s/consul-vault-wan-federation-mesh-communication.svg 'Mesh Federation via Mesh Gateways') @@ -36,7 +36,7 @@ The two data centers will federated using mesh gateways. This communication top In this setup, you will deploy Vault server in the primary datacenter (dc1) Kubernetes cluster, which is also the primary Consul datacenter. You will configure your Vault Helm installation in the secondary datacenter (dc2) Kubernetes cluster to use it as an external server. This way there will be a single vault server cluster that will be used by both Consul datacenters. -~> **Note**: For demonstration purposes, the following example deploys a Vault server in dev mode. Do not use dev mode for production installations. Refer to the [Vault Deployment Guide](https://learn.hashicorp.com/tutorials/vault/raft-deployment-guide) for guidance on how to install Vault in a production setting. +~> **Note**: For demonstration purposes, the following example deploys a Vault server in dev mode. Do not use dev mode for production installations. Refer to the [Vault Deployment Guide](/vault/tutorials/day-one-raft/raft-deployment-guide) for guidance on how to install Vault in a production setting. 1. Change your current Kubernetes context to target the primary datacenter (dc1). @@ -66,7 +66,7 @@ In this setup, you will deploy Vault server in the primary datacenter (dc1) Kube ### Configuring your local environment -1. Install Consul locally so that you can generate the gossip key. Please see the [Precompiled Binaries](/docs/install#precompiled-binaries) section of the [Install Consul page](/docs/install#precompiled-binaries). +1. Install Consul locally so that you can generate the gossip key. Please see the [Precompiled Binaries](/consul/docs/install#precompiled-binaries) section of the [Install Consul page](/consul/docs/install#precompiled-binaries). 1. Set the VAULT_TOKEN with a default value. @@ -126,7 +126,7 @@ Repeat the following steps for each datacenter in the cluster: 1. Enable Vault as the Secrets Backend in the Consul datacenter ### Configure Vault Secrets engines -1. Enable [Vault KV secrets engine - Version 2](https://www.vaultproject.io/docs/secrets/kv/kv-v2) in order to store the [Gossip Encryption Key](/docs/k8s/helm#v-global-acls-replicationtoken) and the ACL Replication token ([`global.acls.replicationToken`](/docs/k8s/helm#v-global-acls-replicationtoken)). +1. Enable [Vault KV secrets engine - Version 2](/vault/docs/secrets/kv/kv-v2) in order to store the [Gossip Encryption Key](/consul/docs/k8s/helm#v-global-acls-replicationtoken) and the ACL Replication token ([`global.acls.replicationToken`](/consul/docs/k8s/helm#v-global-acls-replicationtoken)). ```shell-session $ vault secrets enable -path=consul kv-v2 @@ -184,7 +184,7 @@ Repeat the following steps for each datacenter in the cluster: $ vault write auth/kubernetes-dc1/config kubernetes_host=https://kubernetes.default.svc ``` -1. Enable Vault as the secrets backend in the primary datacenter (dc1). However, you will not yet apply the Helm install command. You will issue the Helm upgrade command after the [Data Integration](/docs/k8s/deployment-configurations/vault/wan-federation#setup-per-consul-datacenter-1) section. +1. Enable Vault as the secrets backend in the primary datacenter (dc1). However, you will not yet apply the Helm install command. You will issue the Helm upgrade command after the [Data Integration](/consul/docs/k8s/deployment-configurations/vault/wan-federation#setup-per-consul-datacenter-1) section. @@ -286,7 +286,7 @@ Repeat the following steps for each datacenter in the cluster: kubernetes_ca_cert="${K8S_DC2_CA_CERT}" ``` -1. Enable Vault as the secrets backend in the secondary Consul datacenter (dc2). However, you will not yet apply the Helm install command. You will issue the Helm upgrade command after the [Data Integration](/docs/k8s/deployment-configurations/vault/wan-federation#setup-per-consul-datacenter-1) section. +1. Enable Vault as the secrets backend in the secondary Consul datacenter (dc2). However, you will not yet apply the Helm install command. You will issue the Helm upgrade command after the [Data Integration](/consul/docs/k8s/deployment-configurations/vault/wan-federation#setup-per-consul-datacenter-1) section. @@ -673,4 +673,4 @@ Repeat the following steps for each datacenter in the cluster: ## Next steps You have completed the process of federating the secondary datacenter (dc2) with the primary datacenter (dc1) using Vault as the Secrets backend. To validate that everything is configured properly, please confirm that all pods within both datacenters are in a running state. -For further detail on specific Consul secrets that are available to be stored in Vault, please checkout the detailed information in the [Data Integration](/docs/k8s/deployment-configurations/vault/data-integration) section of the [Vault as a Secrets Backend](/docs/k8s/deployment-configurations/vault) area of the Consul on Kubernetes documentation. +For further detail on specific Consul secrets that are available to be stored in Vault, please checkout the detailed information in the [Data Integration](/consul/docs/k8s/deployment-configurations/vault/data-integration) section of the [Vault as a Secrets Backend](/consul/docs/k8s/deployment-configurations/vault) area of the Consul on Kubernetes documentation. diff --git a/website/content/docs/k8s/dns.mdx b/website/content/docs/k8s/dns.mdx index c5c89c8347..5082919bd1 100644 --- a/website/content/docs/k8s/dns.mdx +++ b/website/content/docs/k8s/dns.mdx @@ -8,7 +8,7 @@ description: >- # Resolve Consul DNS Requests in Kubernetes One of the primary query interfaces to Consul is the -[DNS interface](/docs/discovery/dns). You can configure Consul DNS in +[DNS interface](/consul/docs/discovery/dns). You can configure Consul DNS in Kubernetes using a [stub-domain configuration](https://kubernetes.io/docs/tasks/administer-cluster/dns-custom-nameservers/#configure-stub-domain-and-upstream-dns-servers) if using KubeDNS or a [proxy configuration](https://coredns.io/plugins/proxy/) if using CoreDNS. @@ -17,12 +17,12 @@ Once configured, DNS requests in the form `.service.consul` resolve for services in Consul. This will work from all Kubernetes namespaces. -> **Note:** If you want requests to just `` (without the `.service.consul`) to resolve, then you'll need -to turn on [Consul to Kubernetes Service Sync](/docs/k8s/service-sync#consul-to-kubernetes). +to turn on [Consul to Kubernetes Service Sync](/consul/docs/k8s/service-sync#consul-to-kubernetes). ## Consul DNS Cluster IP To configure KubeDNS or CoreDNS you'll first need the `ClusterIP` of the Consul -DNS service created by the [Helm chart](/docs/k8s/helm). +DNS service created by the [Helm chart](/consul/docs/k8s/helm). The default name of the Consul DNS service will be `consul-dns`. Use that name to get the `ClusterIP`: diff --git a/website/content/docs/k8s/helm.mdx b/website/content/docs/k8s/helm.mdx index cffac2724c..f9cf059b77 100644 --- a/website/content/docs/k8s/helm.mdx +++ b/website/content/docs/k8s/helm.mdx @@ -222,13 +222,13 @@ Use these links to navigate to a particular top-level stanza. - `authMethodPath` ((#v-global-secretsbackend-vault-connectca-authmethodpath)) (`string: kubernetes`) - The mount path of the Kubernetes auth method in Vault. - `rootPKIPath` ((#v-global-secretsbackend-vault-connectca-rootpkipath)) (`string: ""`) - The path to a PKI secrets engine for the root certificate. - For more details, please refer to [Vault Connect CA configuration](https://www.consul.io/docs/connect/ca/vault#rootpkipath). + For more details, please refer to [Vault Connect CA configuration](/consul/docs/connect/ca/vault#rootpkipath). - `intermediatePKIPath` ((#v-global-secretsbackend-vault-connectca-intermediatepkipath)) (`string: ""`) - The path to a PKI secrets engine for the generated intermediate certificate. - For more details, please refer to [Vault Connect CA configuration](https://www.consul.io/docs/connect/ca/vault#intermediatepkipath). + For more details, please refer to [Vault Connect CA configuration](/consul/docs/connect/ca/vault#intermediatepkipath). - `additionalConfig` ((#v-global-secretsbackend-vault-connectca-additionalconfig)) (`string: {}`) - Additional Connect CA configuration in JSON format. - Please refer to [Vault Connect CA configuration](https://www.consul.io/docs/connect/ca/vault#configuration) + Please refer to [Vault Connect CA configuration](/consul/docs/connect/ca/vault#configuration) for all configuration options available for that provider. Example: @@ -319,7 +319,7 @@ Use these links to navigate to a particular top-level stanza. - `enabled` ((#v-global-tls-enabled)) (`boolean: false`) - If true, the Helm chart will enable TLS for Consul servers and clients and all consul-k8s-control-plane components, as well as generate certificate authority (optional) and server and client certificates. - This setting is required for [Cluster Peering](/docs/connect/cluster-peering/k8s). + This setting is required for [Cluster Peering](/consul/docs/connect/cluster-peering/k8s). - `enableAutoEncrypt` ((#v-global-tls-enableautoencrypt)) (`boolean: false`) - If true, turns on the auto-encrypt feature on clients and servers. It also switches consul-k8s-control-plane components to retrieve the CA from the servers @@ -482,7 +482,7 @@ Use these links to navigate to a particular top-level stanza. This address must be reachable from the Consul servers in the primary datacenter. This auth method will be used to provision ACL tokens for Consul components and is different from the one used by the Consul Service Mesh. - Please see the [Kubernetes Auth Method documentation](https://consul.io/docs/acl/auth-methods/kubernetes). + Please see the [Kubernetes Auth Method documentation](/consul/docs/acl/auth-methods/kubernetes). You can retrieve this value from your `kubeconfig` by running: @@ -662,11 +662,11 @@ Use these links to navigate to a particular top-level stanza. storage classes, the PersistentVolumeClaims would need to be manually created. A `null` value will use the Kubernetes cluster's default StorageClass. If a default StorageClass does not exist, you will need to create one. - Refer to the [Read/Write Tuning](https://www.consul.io/docs/install/performance#read-write-tuning) + Refer to the [Read/Write Tuning](/consul/docs/install/performance#read-write-tuning) section of the Server Performance Requirements documentation for considerations around choosing a performant storage class. - ~> **Note:** The [Reference Architecture](https://learn.hashicorp.com/tutorials/consul/reference-architecture#hardware-sizing-for-consul-servers) + ~> **Note:** The [Reference Architecture](/consul/tutorials/production-deploy/reference-architecture#hardware-sizing-for-consul-servers) contains best practices and recommendations for selecting suitable hardware sizes for your Consul servers. @@ -1876,11 +1876,11 @@ Use these links to navigate to a particular top-level stanza. ### meshGateway ((#h-meshgateway)) -- `meshGateway` ((#v-meshgateway)) - [Mesh Gateways](/docs/connect/gateways/mesh-gateway) enable Consul Connect to work across Consul datacenters. +- `meshGateway` ((#v-meshgateway)) - [Mesh Gateways](/consul/docs/connect/gateways/mesh-gateway) enable Consul Connect to work across Consul datacenters. - - `enabled` ((#v-meshgateway-enabled)) (`boolean: false`) - If [mesh gateways](/docs/connect/gateways/mesh-gateway) are enabled, a Deployment will be created that runs + - `enabled` ((#v-meshgateway-enabled)) (`boolean: false`) - If [mesh gateways](/consul/docs/connect/gateways/mesh-gateway) are enabled, a Deployment will be created that runs gateways and Consul Connect will be configured to use gateways. - This setting is required for [Cluster Peering](/docs/connect/cluster-peering/k8s). + This setting is required for [Cluster Peering](/consul/docs/connect/cluster-peering/k8s). Requirements: consul 1.6.0+ if using `global.acls.manageSystemACLs``. - `replicas` ((#v-meshgateway-replicas)) (`integer: 1`) - Number of replicas for the Deployment. diff --git a/website/content/docs/k8s/index.mdx b/website/content/docs/k8s/index.mdx index b05564d1d8..f4d0ffe4c3 100644 --- a/website/content/docs/k8s/index.mdx +++ b/website/content/docs/k8s/index.mdx @@ -8,14 +8,14 @@ description: >- # Consul on Kubernetes Consul has many integrations with Kubernetes. You can deploy Consul -to Kubernetes using the [Helm chart](/docs/k8s/installation/install#helm-chart-installation) or [Consul K8s CLI](/docs/k8s/installation/install-cli#consul-k8s-cli-installation), sync services between Consul and +to Kubernetes using the [Helm chart](/consul/docs/k8s/installation/install#helm-chart-installation) or [Consul K8s CLI](/consul/docs/k8s/installation/install-cli#consul-k8s-cli-installation), sync services between Consul and Kubernetes, run Consul Service Mesh, and more. This section documents the official integrations between Consul and Kubernetes. ## Use Cases **Consul Service Mesh**: -Consul can automatically inject the [Consul Service Mesh](/docs/connect) +Consul can automatically inject the [Consul Service Mesh](/consul/docs/connect) sidecar into pods so that they can accept and establish encrypted and authorized network connections with mutual TLS. And because Consul Service Mesh can run anywhere, pods and external services can communicate with each other over a fully encrypted connection. @@ -59,7 +59,7 @@ There are several ways to try Consul with Kubernetes in different environments. - The [Consul and Kubernetes Deployment](/consul/tutorials/kubernetes/kubernetes-deployment-guide?utm_source=docs) tutorial covers the necessary steps to install and configure a new Consul cluster on Kubernetes in production. -- The [Secure Consul and Registered Services on Kubernetes](consul/tutorials/kubernetes/kubernetes-secure-agents?utm_source=docs) tutorial covers +- The [Secure Consul and Registered Services on Kubernetes](https://consul.io/consul/tutorials/kubernetes/kubernetes-secure-agents?utm_source=docs) tutorial covers the necessary steps to secure a Consul cluster running on Kubernetes in production. - The [Layer 7 Observability with Consul Service Mesh](/consul/tutorials/kubernetes/kubernetes-layer7-observability) tutorial covers monitoring a @@ -67,5 +67,5 @@ There are several ways to try Consul with Kubernetes in different environments. ### Documentation -- [Installing Consul](/docs/k8s/installation/install) covers how to install Consul using the Helm chart. -- [Helm Chart Reference](/docs/k8s/helm) describes the different options for configuring the Helm chart. +- [Installing Consul](/consul/docs/k8s/installation/install) covers how to install Consul using the Helm chart. +- [Helm Chart Reference](/consul/docs/k8s/helm) describes the different options for configuring the Helm chart. diff --git a/website/content/docs/k8s/installation/install-cli.mdx b/website/content/docs/k8s/installation/install-cli.mdx index 8b3fedfefe..a628ede957 100644 --- a/website/content/docs/k8s/installation/install-cli.mdx +++ b/website/content/docs/k8s/installation/install-cli.mdx @@ -7,7 +7,7 @@ description: >- # Install Consul on Kubernetes from Consul K8s CLI -This topic describes how to install Consul on Kubernetes using the Consul K8s CLI tool. The Consul K8s CLI tool enables you to quickly install and interact with Consul on Kubernetes. Use the Consul K8s CLI tool to install Consul on Kubernetes if you are deploying a single cluster. We recommend using the [Helm chart installation method](/docs/k8s/installation/install) if you are installing Consul on Kubernetes for multi-cluster deployments that involve cross-partition or cross datacenter communication. +This topic describes how to install Consul on Kubernetes using the Consul K8s CLI tool. The Consul K8s CLI tool enables you to quickly install and interact with Consul on Kubernetes. Use the Consul K8s CLI tool to install Consul on Kubernetes if you are deploying a single cluster. We recommend using the [Helm chart installation method](/consul/docs/k8s/installation/install) if you are installing Consul on Kubernetes for multi-cluster deployments that involve cross-partition or cross datacenter communication. ## Introduction @@ -21,7 +21,7 @@ If it is your first time installing Consul on Kubernetes, then you must first in - Ubuntu/Debian: apt - CentOS/RHEL: yum -You must install the correct version of the CLI for your Consul on Kubernetes deployment. To deploy a previous version of Consul on Kubernetes, download the specific version of the CLI that matches the version of the control plane that you would like to deploy. Refer to the [compatibility matrix](/docs/k8s/compatibility) for details. +You must install the correct version of the CLI for your Consul on Kubernetes deployment. To deploy a previous version of Consul on Kubernetes, download the specific version of the CLI that matches the version of the control plane that you would like to deploy. Refer to the [compatibility matrix](/consul/docs/k8s/compatibility) for details. ## Install the CLI @@ -119,7 +119,7 @@ The [Homebrew](https://brew.sh) package manager is required to complete the foll ### Install a previous version -Complete the following instructions to install a specific version of the CLI so that your tool is compatible with your Consul on Kubernetes control plane. Refer to the [compatibility matrix](/docs/k8s/compatibility) for additional information. +Complete the following instructions to install a specific version of the CLI so that your tool is compatible with your Consul on Kubernetes control plane. Refer to the [compatibility matrix](/consul/docs/k8s/compatibility) for additional information. @@ -217,7 +217,7 @@ Complete the following instructions to install a specific version of the CLI so ## Install Consul on Kubernetes -After installing the Consul K8s CLI tool (`consul-k8s`), issue the `install` subcommand and any additional options to install Consul on your existing Kubernetes cluster. Refer to the [Consul K8s CLI reference](/docs/k8s/k8s-cli) for details about all commands and available options. If you do not include any additional options, the `consul-k8s` CLI installs Consul on Kubernetes using the default settings form the Consul Helm chart values. The following example installs Consul on Kubernetes with service mesh and CRDs enabled. +After installing the Consul K8s CLI tool (`consul-k8s`), issue the `install` subcommand and any additional options to install Consul on your existing Kubernetes cluster. Refer to the [Consul K8s CLI reference](/consul/docs/k8s/k8s-cli) for details about all commands and available options. If you do not include any additional options, the `consul-k8s` CLI installs Consul on Kubernetes using the default settings form the Consul Helm chart values. The following example installs Consul on Kubernetes with service mesh and CRDs enabled. ```shell-session $ consul-k8s install @@ -245,7 +245,7 @@ No existing installations found. You can include the `-auto-approve` option set to `true` to proceed with the installation if the pre-install checks pass. -The pre-install checks may fail if existing `PersistentVolumeClaims` (PVC) are detected. Refer to the [uninstall instructions](/docs/k8s/operations/uninstall#uninstall-consul) for information about removing PVCs. +The pre-install checks may fail if existing `PersistentVolumeClaims` (PVC) are detected. Refer to the [uninstall instructions](/consul/docs/k8s/operations/uninstall#uninstall-consul) for information about removing PVCs. ## Check the Consul cluster status diff --git a/website/content/docs/k8s/installation/install.mdx b/website/content/docs/k8s/installation/install.mdx index 786c49412f..2872718166 100644 --- a/website/content/docs/k8s/installation/install.mdx +++ b/website/content/docs/k8s/installation/install.mdx @@ -7,21 +7,21 @@ description: >- # Install Consul on Kubernetes with Helm -This topic describes how to install Consul on Kubernetes using the official Consul Helm chart. For instruction on how to install Consul on Kubernetes using the Consul K8s CLI, refer to [Installing the Consul K8s CLI](/docs/k8s/installation/install-cli). +This topic describes how to install Consul on Kubernetes using the official Consul Helm chart. For instruction on how to install Consul on Kubernetes using the Consul K8s CLI, refer to [Installing the Consul K8s CLI](/consul/docs/k8s/installation/install-cli). ## Introduction We recommend using the Consul Helm chart to install Consul on Kubernetes for multi-cluster installations that involve cross-partition or cross datacenter communication. The Helm chart installs and configures all necessary components to run Consul. -Consul can run directly on Kubernetes so that you can leverage Consul functionality if your workloads are fully deployed to Kubernetes. For heterogeneous workloads, Consul agents can join a server running inside or outside of Kubernetes. Refer to the [Consul on Kubernetes architecture](/docs/k8s/architecture) to learn more about its general architecture. +Consul can run directly on Kubernetes so that you can leverage Consul functionality if your workloads are fully deployed to Kubernetes. For heterogeneous workloads, Consul agents can join a server running inside or outside of Kubernetes. Refer to the [Consul on Kubernetes architecture](/consul/docs/k8s/architecture) to learn more about its general architecture. The Helm chart exposes several useful configurations and automatically sets up complex resources, but it does not automatically operate Consul. You must still become familiar with how to monitor, backup, and upgrade the Consul cluster. -The Helm chart has no required configuration, so it installs a Consul cluster with default configurations. We strongly recommend that you [learn about the configuration options](/docs/k8s/helm#configuration-values) before going to production. +The Helm chart has no required configuration, so it installs a Consul cluster with default configurations. We strongly recommend that you [learn about the configuration options](/consul/docs/k8s/helm#configuration-values) before going to production. --> **Security warning**: By default, Helm installs Consul with security configurations disabled so that the out-of-box experience is optimized for new users. We strongly recommend using a properly-secured Kubernetes cluster or making sure that you understand and enable [Consul’s security features](/docs/security) before going into production. Some security features are not supported in the Helm chart and require additional manual configuration. +-> **Security warning**: By default, Helm installs Consul with security configurations disabled so that the out-of-box experience is optimized for new users. We strongly recommend using a properly-secured Kubernetes cluster or making sure that you understand and enable [Consul’s security features](/consul/docs/security) before going into production. Some security features are not supported in the Helm chart and require additional manual configuration. -Refer to the [architecture](/docs/k8s/installation/install#architecture) section to learn more about the general architecture of Consul on Kubernetes. +Refer to the [architecture](/consul/docs/k8s/installation/install#architecture) section to learn more about the general architecture of Consul on Kubernetes. For a hands-on experience with Consul as a service mesh for Kubernetes, follow the [Getting Started with Consul service @@ -81,11 +81,11 @@ Using the Helm Chart requires Helm version 3.6+. Visit the [Helm website](https: If you want to customize your installation, create a `values.yaml` file to override the default settings. To learn what settings are available, run `helm inspect values hashicorp/consul` -or read the [Helm Chart Reference](/docs/k8s/helm). +or read the [Helm Chart Reference](/consul/docs/k8s/helm). ### Minimal `values.yaml` for Consul service mesh -The following `values.yaml` config file contains the minimum required settings to enable [Consul Service Mesh]((/docs/k8s/connect)): +The following `values.yaml` config file contains the minimum required settings to enable [Consul Service Mesh](https://consul.io/(/docs/k8s/connect)): @@ -106,7 +106,7 @@ NAME: consul ### Enable the Consul CNI plugin -By default, Consul injects a `connect-inject-init` init container as part of the Kubernetes pod startup process when Consul is in [transparent proxy mode](/docs/connect/transparent-proxy). +By default, Consul injects a `connect-inject-init` init container as part of the Kubernetes pod startup process when Consul is in [transparent proxy mode](/consul/docs/connect/transparent-proxy). The container configures traffic redirection in the service mesh through the sidecar proxy. To configure redirection, the container requires elevated `CAP_NET_ADMIN` privileges, which may not be compatible with security policies in your organization. @@ -228,7 +228,7 @@ By default, Consul Service Mesh is enabled on almost all namespaces within a Kub ### Update your Consul on Kubernetes configuration If you already installed Consul and want to make changes, you need to run -`helm upgrade`. Refer to [Upgrading](/docs/k8s/upgrade) for more details. +`helm upgrade`. Refer to [Upgrading](/consul/docs/k8s/upgrade) for more details. ## Usage @@ -286,13 +286,13 @@ with less permissions. #### Exposing the UI through a service If you want to expose the UI via a Kubernetes Service, configure -the [`ui.service` chart values](/docs/k8s/helm#v-ui-service). +the [`ui.service` chart values](/consul/docs/k8s/helm#v-ui-service). Because this service allows requests to the Consul servers, it should not be open to the world. ### Accessing the Consul HTTP API -While technically any listening agent can respond to the HTTP API, communicating with the local Consul node has important caching behavior and allows you to use the simpler [`/agent` endpoints for services and checks](/api-docs/agent). +While technically any listening agent can respond to the HTTP API, communicating with the local Consul node has important caching behavior and allows you to use the simpler [`/agent` endpoints for services and checks](/consul/api-docs/agent). To find information about a node, you can use the [downward API](https://kubernetes.io/docs/tasks/inject-data-application/downward-api-volume-expose-pod-information/). @@ -363,7 +363,7 @@ spec: ## Next Steps -If you are still considering a move to Kubernetes, or to Consul on Kubernetes specifically, our [Migrate to Microservices with Consul Service Mesh on Kubernetes](https://learn.hashicorp.com/collections/consul/microservices?utm_source=docs) +If you are still considering a move to Kubernetes, or to Consul on Kubernetes specifically, our [Migrate to Microservices with Consul Service Mesh on Kubernetes](/consul/tutorials/microservices?utm_source=docs) collection uses an example application written by a fictional company to illustrate why and how organizations can migrate from monolith to microservices using Consul service mesh on Kubernetes. The case study in this collection should provide information valuable for understanding how to develop services that leverage Consul during any stage diff --git a/website/content/docs/k8s/k8s-cli.mdx b/website/content/docs/k8s/k8s-cli.mdx index 2e96017bd8..402d2327b7 100644 --- a/website/content/docs/k8s/k8s-cli.mdx +++ b/website/content/docs/k8s/k8s-cli.mdx @@ -8,11 +8,11 @@ description: >- # Consul on Kubernetes CLI Reference The Consul on Kubernetes CLI, `consul-k8s`, is a tool for managing Consul -that does not require direct interaction with Helm, the [Consul CLI](/commands), +that does not require direct interaction with Helm, the [Consul CLI](/consul/commands), or `kubectl`. For guidance on how to install `consul-k8s`, refer to the -[Installing the Consul K8s CLI](/docs/k8s/installation/install-cli) documentation. +[Installing the Consul K8s CLI](/consul/docs/k8s/installation/install-cli) documentation. This topic describes the commands and available options for using `consul-k8s`. @@ -120,13 +120,13 @@ This command lists proxies and their `Type`. Types of proxies include: - `Sidecar`: The majority of pods in the cluster are `Sidecar` types. They run the proxy as a sidecar to connect the pod as a service in the mesh. - `API Gateway`: These pods run a proxy to manage connections with networks - outside of the Consul cluster. Read more about [API gateways](/docs/api-gateway). + outside of the Consul cluster. Read more about [API gateways](/consul/docs/api-gateway). - `Ingress Gateway`: These pods run a proxy to manage ingress into the - Kubernetes cluster. Read more about [ingress gateways](/docs/k8s/connect/ingress-gateways). + Kubernetes cluster. Read more about [ingress gateways](/consul/docs/k8s/connect/ingress-gateways). - `Terminating Gateway`: These pods run a proxy to control connections to - external services. Read more about [terminating gateways](/docs/k8s/connect/terminating-gateways). + external services. Read more about [terminating gateways](/consul/docs/k8s/connect/terminating-gateways). - `Mesh Gateway`: These pods run a proxy to manage connections between - Consul clusters connected using mesh federation. Read more about [Consul Mesh Federation](/docs/k8s/deployment-configurations/multi-cluster/kubernetes). + Consul clusters connected using mesh federation. Read more about [Consul Mesh Federation](/consul/docs/k8s/deployment-configurations/multi-cluster/kubernetes). #### Example Commands @@ -189,7 +189,7 @@ $ consul-k8s proxy read The command takes a required value, ``. This should be the full name of a Kubernetes Pod. If a Pod is running more than one Envoy proxy managed by -Consul, as in the [Multiport configuration](https://www.consul.io/docs/k8s/connect#kubernetes-pods-with-multiple-ports), +Consul, as in the [Multiport configuration](/consul/docs/k8s/connect#kubernetes-pods-with-multiple-ports), configuration for all proxies in the Pod will be displayed. The following options are available. diff --git a/website/content/docs/k8s/operations/certificate-rotation.mdx b/website/content/docs/k8s/operations/certificate-rotation.mdx index 939771054a..85f86a7b9c 100644 --- a/website/content/docs/k8s/operations/certificate-rotation.mdx +++ b/website/content/docs/k8s/operations/certificate-rotation.mdx @@ -12,7 +12,7 @@ are issued every time the Helm chart is upgraded. These certificates are signed continue to work as expected in the existing cluster. Consul servers read the certificates from Kubernetes secrets during start-up and keep them in memory. In order to ensure the -servers use the newer certificate, the server pods need to be [restarted explicitly](/docs/k8s/upgrade#upgrading-consul-servers) in +servers use the newer certificate, the server pods need to be [restarted explicitly](/consul/docs/k8s/upgrade#upgrading-consul-servers) in a situation where `helm upgrade` does not restart the server pods. To explicitly perform server certificate rotation, follow these steps: @@ -25,4 +25,4 @@ To explicitly perform server certificate rotation, follow these steps: This should run the `tls-init` job that will generate new Server certificates. -1. Restart the Server pods following the steps [here](/docs/k8s/upgrade#upgrading-consul-servers). +1. Restart the Server pods following the steps [here](/consul/docs/k8s/upgrade#upgrading-consul-servers). diff --git a/website/content/docs/k8s/operations/gossip-encryption-key-rotation.mdx b/website/content/docs/k8s/operations/gossip-encryption-key-rotation.mdx index add04dd4a2..df49d79b18 100644 --- a/website/content/docs/k8s/operations/gossip-encryption-key-rotation.mdx +++ b/website/content/docs/k8s/operations/gossip-encryption-key-rotation.mdx @@ -7,9 +7,9 @@ description: >- # Rotate Gossip Encryption Keys for Consul on Kubernetes -The following instructions provides a step-by-step manual process for rotating [gossip encryption](/docs/security/encryption#gossip-encryption) keys on Consul clusters that are deployed onto a Kubernetes cluster with Consul on Kubernetes. +The following instructions provides a step-by-step manual process for rotating [gossip encryption](/consul/docs/security/encryption#gossip-encryption) keys on Consul clusters that are deployed onto a Kubernetes cluster with Consul on Kubernetes. -The following steps need only be performed once in any single datacenter if your Consul clusters are [federated](/docs/k8s/deployment-configurations/multi-cluster/kubernetes). Rotating the gossip encryption key in one datacenter will automatically rotate the gossip encryption key for all the other datacenters. +The following steps need only be performed once in any single datacenter if your Consul clusters are [federated](/consul/docs/k8s/deployment-configurations/multi-cluster/kubernetes). Rotating the gossip encryption key in one datacenter will automatically rotate the gossip encryption key for all the other datacenters. -> **Note:** Careful precaution should be taken to prohibit new clients from joining during the gossip encryption rotation process, otherwise the new clients will join the gossip pool without knowledge of the new primary gossip encryption key. In addition, deletion of a gossip encryption key from the keyring should occur only after clients have safely migrated to utilizing the new gossip encryption key for communication. @@ -18,7 +18,7 @@ The following steps need only be performed once in any single datacenter if your ```shell-session $ kubectl config set-context --current --namespace=consul ``` -1. Generate a new key and store in safe place for retrieval in the future ([Vault KV Secrets Engine](https://www.vaultproject.io/docs/secrets/kv/kv-v2#usage) is a recommended option). +1. Generate a new key and store in safe place for retrieval in the future ([Vault KV Secrets Engine](/vault/docs/secrets/kv/kv-v2#usage) is a recommended option). ```shell-session $ consul keygen @@ -128,7 +128,7 @@ The following steps need only be performed once in any single datacenter if your     - -> **Note:** These Vault instructions assume that you have integrated your [Gossip encryption key](/docs/k8s/deployment-configurations/vault/data-integration/gossip) using [Vault as a Secrets Backend](/docs/k8s/deployment-configurations/vault). + -> **Note:** These Vault instructions assume that you have integrated your [Gossip encryption key](/consul/docs/k8s/deployment-configurations/vault/data-integration/gossip) using [Vault as a Secrets Backend](/consul/docs/k8s/deployment-configurations/vault). Update the gossip encryption Vault Secret with the value of the new gossip encryption key to ensure that subsequent `helm upgrades` commands execute successfully. The name of the secret that stores the value of the gossip encryption key can be found in the Helm values file: diff --git a/website/content/docs/k8s/operations/tls-on-existing-cluster.mdx b/website/content/docs/k8s/operations/tls-on-existing-cluster.mdx index 96c20e27db..ee656f2438 100644 --- a/website/content/docs/k8s/operations/tls-on-existing-cluster.mdx +++ b/website/content/docs/k8s/operations/tls-on-existing-cluster.mdx @@ -34,7 +34,7 @@ If you do not use a service mesh, follow this process. This upgrade trigger a rolling update of `consul-k8s` components. 1. Perform a rolling upgrade of the servers, as described in - [Upgrade Consul Servers](/docs/k8s/upgrade#upgrading-consul-servers). + [Upgrade Consul Servers](/consul/docs/k8s/upgrade#upgrading-consul-servers). 1. Repeat steps 1 and 2, turning on TLS verification by setting `global.tls.verify` to `true`. @@ -71,7 +71,7 @@ applications to it. ``` In this configuration, we're setting `server.updatePartition` to the number of - server replicas as described in [Upgrade Consul Servers](/docs/k8s/upgrade#upgrading-consul-servers). + server replicas as described in [Upgrade Consul Servers](/consul/docs/k8s/upgrade#upgrading-consul-servers). 1. Run `helm upgrade` with the above config file. @@ -84,7 +84,7 @@ applications to it. the sidecar proxy. Also, Kubernetes should schedule these applications on the new node pool. 1. Perform a rolling upgrade of the servers described in - [Upgrade Consul Servers](/docs/k8s/upgrade#upgrading-consul-servers). + [Upgrade Consul Servers](/consul/docs/k8s/upgrade#upgrading-consul-servers). 1. If everything is healthy, delete the old node pool. diff --git a/website/content/docs/k8s/operations/uninstall.mdx b/website/content/docs/k8s/operations/uninstall.mdx index 86a8074dc3..3d780df183 100644 --- a/website/content/docs/k8s/operations/uninstall.mdx +++ b/website/content/docs/k8s/operations/uninstall.mdx @@ -23,7 +23,7 @@ In the following example, Consul will be uninstalled and the data removed withou $ consul-k8s uninstall -auto-approve=true -wipe-data=true ``` -Refer to the [Consul K8s CLI reference](/docs/k8s/k8s-cli#uninstall) topic for details. +Refer to the [Consul K8s CLI reference](/consul/docs/k8s/k8s-cli#uninstall) topic for details. ## Helm commands diff --git a/website/content/docs/k8s/platforms/self-hosted-kubernetes.mdx b/website/content/docs/k8s/platforms/self-hosted-kubernetes.mdx index 42bef6a43a..e5f1f0031f 100644 --- a/website/content/docs/k8s/platforms/self-hosted-kubernetes.mdx +++ b/website/content/docs/k8s/platforms/self-hosted-kubernetes.mdx @@ -10,7 +10,7 @@ description: >- Except for creating persistent volumes and ensuring there is a storage class configured (see below), installing Consul on your self-hosted Kubernetes cluster is the same process as installing Consul on a -cloud-hosted Kubernetes cluster. See the [Installation Overview](/docs/k8s/installation/install) +cloud-hosted Kubernetes cluster. See the [Installation Overview](/consul/docs/k8s/installation/install) for install instructions. ## Predefined Persistent Volume Claims (PVCs) @@ -49,4 +49,4 @@ server: storageClass: your-class ``` -See the [Helm reference](/docs/k8s/helm#v-server-storageclass) for that setting for more information. +See the [Helm reference](/consul/docs/k8s/helm#v-server-storageclass) for that setting for more information. diff --git a/website/content/docs/k8s/service-sync.mdx b/website/content/docs/k8s/service-sync.mdx index f63fa88c4b..0cd6cb7c38 100644 --- a/website/content/docs/k8s/service-sync.mdx +++ b/website/content/docs/k8s/service-sync.mdx @@ -12,7 +12,7 @@ services are available to Consul agents and services in Consul can be available as first-class Kubernetes services. This functionality is provided by the [consul-k8s project](https://github.com/hashicorp/consul-k8s) and can be automatically installed and configured using the -[Consul Helm chart](/docs/k8s/installation/install). +[Consul Helm chart](/consul/docs/k8s/installation/install). ![screenshot of a Kubernetes service in the UI](/img/k8s-service.png) @@ -20,7 +20,7 @@ automatically installed and configured using the Consul catalog enable Kubernetes services to be accessed by any node that is part of the Consul cluster, including other distinct Kubernetes clusters. For non-Kubernetes nodes, they can access services using the standard -[Consul DNS](/docs/discovery/dns) or HTTP API. +[Consul DNS](/consul/docs/discovery/dns) or HTTP API. **Why sync Consul services to Kubernetes?** Syncing Consul services to Kubernetes services enables non-Kubernetes services to be accessed using kube-dns and Kubernetes-specific @@ -29,13 +29,13 @@ service discovery, including hosted services like databases. ## Installation and configuration -~> Enabling both Service Mesh and Service Sync on the same Kubernetes services is not supported, as Service Mesh also registers Kubernetes service instances to Consul. Ensure that Service Sync is only enabled for namespaces and services that are not injected with the Consul sidecar for Service Mesh as described in [Sync Enable/Disable](/docs/k8s/service-sync#sync-enable-disable). +~> Enabling both Service Mesh and Service Sync on the same Kubernetes services is not supported, as Service Mesh also registers Kubernetes service instances to Consul. Ensure that Service Sync is only enabled for namespaces and services that are not injected with the Consul sidecar for Service Mesh as described in [Sync Enable/Disable](/consul/docs/k8s/service-sync#sync-enable-disable). The service sync uses an external long-running process in the [consul-k8s project](https://github.com/hashicorp/consul-k8s). This process can run either inside or outside of a Kubernetes cluster. However, running this process within the Kubernetes cluster is generally easier since it is automated using the -[Helm chart](/docs/k8s/helm). +[Helm chart](/consul/docs/k8s/helm). The Consul server cluster can run either in or out of a Kubernetes cluster. The Consul server cluster does not need to be running on the same machine @@ -44,7 +44,7 @@ with the address to a Consul agent as well as any additional access information such as ACL tokens. To install the sync process, enable the catalog sync feature using -[Helm values](/docs/k8s/helm#configuration-values) and +[Helm values](/consul/docs/k8s/helm#configuration-values) and upgrade the installation using `helm upgrade` for existing installs or `helm install` for a fresh install. @@ -73,7 +73,7 @@ syncCatalog: toK8S: false ``` -Refer to the [Helm configuration](/docs/k8s/helm#v-synccatalog) +Refer to the [Helm configuration](/consul/docs/k8s/helm#v-synccatalog) for more information. ### Authentication @@ -89,9 +89,9 @@ for both in-cluster and out-of-cluster authentication. If `kubectl` works, then the sync program should work. If ACLs are configured on the Consul cluster, you need to provide a Consul -[ACL token](/consul/tutorials/security/access-control-setup-production). Review the [ACL rules](/docs/security/acl/acl-rules) +[ACL token](/consul/tutorials/security/access-control-setup-production). Review the [ACL rules](/consul/docs/security/acl/acl-rules) when creating this token so that it only allows the necessary privileges. The catalog -sync process accepts this token by using the [`CONSUL_HTTP_TOKEN`](/commands#consul_http_token) +sync process accepts this token by using the [`CONSUL_HTTP_TOKEN`](/consul/commands#consul_http_token) environment variable. This token should be set as a [Kubernetes secret](https://kubernetes.io/docs/concepts/configuration/secret/#creating-your-own-secrets) and referenced in the Helm chart. @@ -127,10 +127,10 @@ node that has the representative pod running. While Kubernetes configures a static port on all nodes in the cluster, this limits the number of service instances to be equal to the nodes running the target pods. By default it uses the external IP of the node but this can be configured through -the [`nodePortSyncType` helm option](/docs/k8s/helm#v-synccatalog-nodeportsynctype). +the [`nodePortSyncType` helm option](/consul/docs/k8s/helm#v-synccatalog-nodeportsynctype). The service instance's port is set to the first defined node port of the service unless -set specifically in the `consul.hashicorp.com/service-port` annotation. Refer to [Service Ports](/docs/k8s/service-sync#service-ports) for more information. +set specifically in the `consul.hashicorp.com/service-port` annotation. Refer to [Service Ports](/consul/docs/k8s/service-sync#service-ports) for more information. #### LoadBalancer @@ -140,7 +140,7 @@ balancer, only one service instance is registered with Consul rather than registering each individual pod endpoint. The service instance's port is set to the first defined port of the -service unless set specifically in the `consul.hashicorp.com/service-port` annotation. Refer to [Service Ports](/docs/k8s/service-sync#service-ports) for more information. +service unless set specifically in the `consul.hashicorp.com/service-port` annotation. Refer to [Service Ports](/consul/docs/k8s/service-sync#service-ports) for more information. #### External IPs @@ -155,7 +155,7 @@ for each external IP. It is assumed that if an external IP is present that it is routable and configured by some other system. The service instance's port is set to the _first_ defined port of the -service unless set specifically with the `consul.hashicorp.com/service-port` annotation. Refer to [Service Ports](/docs/k8s/service-sync#service-ports) for more information. +service unless set specifically with the `consul.hashicorp.com/service-port` annotation. Refer to [Service Ports](/consul/docs/k8s/service-sync#service-ports) for more information. #### ClusterIP @@ -163,11 +163,11 @@ ClusterIP services are synced by default as of `consul-k8s` version 0.3.0. Each pod that is an endpoint for the service is synced as a Consul service instance with its IP set to the pod IP and its port set to the `targetPort`. -The service instance's port can be overridden with the `consul.hashicorp.com/service-port` annotation. Refer to [Service Ports](/docs/k8s/service-sync#service-ports) for more information. +The service instance's port can be overridden with the `consul.hashicorp.com/service-port` annotation. Refer to [Service Ports](/consul/docs/k8s/service-sync#service-ports) for more information. -> In Kubernetes clusters where pod IPs are not accessible outside the cluster, the services registered in Consul may not be routable. To -skip syncing ClusterIP services, set [`syncClusterIPServices`](/docs/k8s/helm#v-synccatalog-syncclusteripservices) +skip syncing ClusterIP services, set [`syncClusterIPServices`](/consul/docs/k8s/helm#v-synccatalog-syncclusteripservices) to `false` in the Helm chart values file. ### Enable and disable sync @@ -393,11 +393,11 @@ With Consul To Kubernetes syncing enabled, DNS requests of the form `.`. --> **Note:** Consul to Kubernetes syncing is not required if you enabled [Consul DNS on Kubernetes](/docs/k8s/dns). +-> **Note:** Consul to Kubernetes syncing is not required if you enabled [Consul DNS on Kubernetes](/consul/docs/k8s/dns). All you need to do is address services in the form `.service.consul`, so you do not need Kubernetes `Service` objects created. ~> **Requires Consul DNS via CoreDNS in Kubernetes:** This feature requires that -[Consul DNS](/docs/k8s/dns) is configured within Kubernetes. +[Consul DNS](/consul/docs/k8s/dns) is configured within Kubernetes. Additionally, [CoreDNS](https://kubernetes.io/docs/tasks/administer-cluster/dns-custom-nameservers/#config-coredns) is required instead of kube-dns to resolve an issue with resolving `externalName` services pointing to custom domains. diff --git a/website/content/docs/k8s/upgrade/index.mdx b/website/content/docs/k8s/upgrade/index.mdx index 13b5e25158..ae12c8e3d9 100644 --- a/website/content/docs/k8s/upgrade/index.mdx +++ b/website/content/docs/k8s/upgrade/index.mdx @@ -94,10 +94,10 @@ If you want to upgrade to the latest `0.40.0` version, use the following procedu If a new version of Consul is released, you need to perform a Helm upgrade to update to the new version. Before you upgrade to a new version: -1. Read the [Upgrading Consul](/docs/upgrading) documentation. -1. Read any [specific instructions](/docs/upgrading/upgrade-specific) for the version you want to upgrade +1. Read the [Upgrading Consul](/consul/docs/upgrading) documentation. +1. Read any [specific instructions](/consul/docs/upgrading/upgrade-specific) for the version you want to upgrade to, as well as the Consul [changelog](https://github.com/hashicorp/consul/blob/main/CHANGELOG.md) for that version. -1. Read our [Compatibility Matrix](/docs/k8s/compatibility) to ensure +1. Read our [Compatibility Matrix](/consul/docs/k8s/compatibility) to ensure your current Helm chart version supports this Consul version. If it does not, you may need to also upgrade your Helm chart version at the same time. 1. Set `global.image` in your `values.yaml` to the desired version: @@ -165,7 +165,7 @@ that can be used. 1. Take specific note if `consul-server, StatefulSet` is listed, as it means your Consul server statefulset will be redeployed. If your Consul server statefulset needs to be redeployed, follow the same pattern for upgrades as - on other platforms by redploying servers one by one. Refer tp [Upgrading Consul](/docs/upgrading) for more information. + on other platforms by redploying servers one by one. Refer tp [Upgrading Consul](/consul/docs/upgrading) for more information. If neither the server statefulset is not being redeployed, then you can continue with the Helm upgrade without any specific sequence to follow. @@ -215,7 +215,7 @@ Initiate the server upgrade: ## Upgrading to Consul Dataplane -In earlier versions, Consul on Kubernetes used client agents in its deployments. As of v1.14.0, Consul uses [Consul Dataplane](/docs/connect/dataplane/) in Kubernetes deployments instead of client agents. +In earlier versions, Consul on Kubernetes used client agents in its deployments. As of v1.14.0, Consul uses [Consul Dataplane](/consul/docs/connect/dataplane/) in Kubernetes deployments instead of client agents. If you upgrade Consul from a version that uses client agents to a version the uses dataplanes, complete the following steps to upgrade your deployment safely and without downtime. @@ -242,4 +242,4 @@ If you upgrade Consul from a version that uses client agents to a version the us If you already have a Consul cluster deployed on Kubernetes and would like to turn on TLS for internal Consul communication, -refer to [Configuring TLS on an Existing Cluster](/docs/k8s/operations/tls-on-existing-cluster). +refer to [Configuring TLS on an Existing Cluster](/consul/docs/k8s/operations/tls-on-existing-cluster). diff --git a/website/content/docs/k8s/upgrade/upgrade-cli.mdx b/website/content/docs/k8s/upgrade/upgrade-cli.mdx index 692d497d56..36b30e4a3f 100644 --- a/website/content/docs/k8s/upgrade/upgrade-cli.mdx +++ b/website/content/docs/k8s/upgrade/upgrade-cli.mdx @@ -11,7 +11,7 @@ Consul K8s CLI is a tool for quickly installing and interacting with Consul on K ## Upgrade the CLI -These instructions describe how to upgrade the current installed version of the CLI to the latest version. If you are looking to upgrade to a specific version, please follow [Install a specific version of the CLI](/docs/k8s/installation/install-cli#install-a-specific-version-of-the-cli). +These instructions describe how to upgrade the current installed version of the CLI to the latest version. If you are looking to upgrade to a specific version, please follow [Install a specific version of the CLI](/consul/docs/k8s/installation/install-cli#install-a-specific-version-of-the-cli). diff --git a/website/content/docs/lambda/index.mdx b/website/content/docs/lambda/index.mdx index 1a765478f5..50af9ce6f0 100644 --- a/website/content/docs/lambda/index.mdx +++ b/website/content/docs/lambda/index.mdx @@ -13,24 +13,24 @@ You can configure Consul to allow services in your mesh to invoke Lambda functio The first step is to register your Lambda functions into Consul. We recommend using the [Lambda registrator module](https://github.com/hashicorp/terraform-aws-consul-lambda/tree/main/modules/lambda-registrator) to automatically synchronize Lambda functions into Consul. You can also manually register Lambda functions into Consul if you are unable to use the Lambda registrator. -Refer to [Lambda Function Registration Requirements](/docs/lambda/registration) for additional information about registering Lambda functions into Consul. +Refer to [Lambda Function Registration Requirements](/consul/docs/lambda/registration) for additional information about registering Lambda functions into Consul. ## Invoke Lambda functions from Consul service mesh After registering AWS Lambda functions, you can invoke Lambda functions from the Consul service mesh through terminating gateways (recommended) or directly from connected proxies. -Refer to [Invoke Lambda Functions from Services](/docs/lambda/invocation) for details. +Refer to [Invoke Lambda Functions from Services](/consul/docs/lambda/invocation) for details. ## Invoke mesh services from Lambda function ~> **Lambda-to-mesh functionality is currently in beta**: Functionality associated with beta features are subject to change. You should never use the beta release in secure environments or production scenarios. Features in beta may have performance issues, scaling issues, and limited support. -You can also add the `consul-lambda-extension` plugin as a layer in your Lambda functions, which enables them to send requests to services in the mesh. The plugin starts a lightweight sidecar proxy that directs requests from Lambda functions to [mesh gateways](docs/connect/gateways#mesh-gateways). The gateways route traffic to the destination service to complete the request. +You can also add the `consul-lambda-extension` plugin as a layer in your Lambda functions, which enables them to send requests to services in the mesh. The plugin starts a lightweight sidecar proxy that directs requests from Lambda functions to [mesh gateways](/consul/docs/connect/gateways#mesh-gateways). The gateways route traffic to the destination service to complete the request. ![Invoke mesh service from Lambda function](/img/invoke-service-from-lambda-flow.svg) -Refer to [Invoke Services from Lambda Functions](/docs/lambda/invoke-from-lambda) for additional information about registering Lambda functions into Consul. +Refer to [Invoke Services from Lambda Functions](/consul/docs/lambda/invoke-from-lambda) for additional information about registering Lambda functions into Consul. -Consul mesh gateways are required to send requests from Lambda functions to mesh services. Refer to [Mesh Gateways](/docs/connect/gateways/mesh-gateway) for additional information. +Consul mesh gateways are required to send requests from Lambda functions to mesh services. Refer to [Mesh Gateways](/consul/docs/connect/gateways/mesh-gateway) for additional information. Note that L7 traffic management features are not supported. As a result, requests from Lambda functions ignore service routes and splitters. diff --git a/website/content/docs/lambda/invocation.mdx b/website/content/docs/lambda/invocation.mdx index 73751f8d6d..ebb12571ec 100644 --- a/website/content/docs/lambda/invocation.mdx +++ b/website/content/docs/lambda/invocation.mdx @@ -19,7 +19,7 @@ You can invoke Lambda functions from the Consul service mesh through terminating We recommend invoking Lambda functions through terminating gateways. This method supports cross-datacenter communication, transparent proxies, intentions, and all other Consul service mesh features. -The terminating gateway must have [the appropriate IAM permissions](/docs/lambda/registration#configure-iam-permissions-for-envoy) +The terminating gateway must have [the appropriate IAM permissions](/consul/docs/lambda/registration#configure-iam-permissions-for-envoy) to invoke the function. The following diagram shows the invocation procedure: @@ -60,7 +60,7 @@ The following diagram shows the invocation procedure: ## Invoke a Lambda Function Before you can invoke a Lambda function, register the service used to invoke the Lambda function and the service running in Lambda with -Consul (refer to [registration](/docs/lambda/registration) for +Consul (refer to [registration](/consul/docs/lambda/registration) for instructions). The service used to invoke the function must be deployed to the service mesh. diff --git a/website/content/docs/lambda/invoke-from-lambda.mdx b/website/content/docs/lambda/invoke-from-lambda.mdx index e84fe9a3b8..a7ec291386 100644 --- a/website/content/docs/lambda/invoke-from-lambda.mdx +++ b/website/content/docs/lambda/invoke-from-lambda.mdx @@ -24,7 +24,7 @@ The following steps describe the process: You must add the `consul-lambda-extension` extension as a Lambda layer to enable Lambda functions to send requests to mesh services. Refer to the [AWS Lambda documentation](https://docs.aws.amazon.com/lambda/latest/dg/invocation-layers.html) for instructions on how to add layers to your Lambda functions. -The layer runs an external Lambda extension that starts a sidecar proxy. The proxy listens on one port for each upstream service and upgrades the outgoing connections to mTLS. It then proxies the requests through to [mesh gateways](/docs/connect/gateways#mesh-gateways). +The layer runs an external Lambda extension that starts a sidecar proxy. The proxy listens on one port for each upstream service and upgrades the outgoing connections to mTLS. It then proxies the requests through to [mesh gateways](/consul/docs/connect/gateways#mesh-gateways). ## Prerequisites @@ -86,10 +86,10 @@ spec: The mesh gateway must be running and registered to the Lambda function’s Consul datacenter. Refer to the following documentation and tutorials for instructions: -- [Mesh Gateways between WAN-Federated Datacenters](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters) -- [Mesh Gateways between Admin Partitions](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions) -- [Mesh Gateways between Peered Clusters](/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers) -- [Connect Services Across Datacenters with Mesh Gateways](https://developer.hashicorp.com/consul/tutorials/developer-mesh/service-mesh-gateways) +- [Mesh Gateways between WAN-Federated Datacenters](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-wan-datacenters) +- [Mesh Gateways between Admin Partitions](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-partitions) +- [Mesh Gateways between Peered Clusters](/consul/docs/connect/gateways/mesh-gateway/service-to-service-traffic-peers) +- [Connect Services Across Datacenters with Mesh Gateways](/consul/tutorials/developer-mesh/service-mesh-gateways) ## Deploy the Lambda extension layer @@ -119,7 +119,7 @@ The extension periodically retrieves the data from the AWS Parameter Store so th ## Deploy the Lambda registrator -Configure and deploy the Lambda registrator. Refer to the [registrator configuration documentation](/docs/lambda/registration/automate#configuration) and the [registrator deployment documentation](/docs/lambda/registration/automate#deploy-the-lambda-registrator) for instructions. +Configure and deploy the Lambda registrator. Refer to the [registrator configuration documentation](/consul/docs/lambda/registration/automate#configuration) and the [registrator deployment documentation](/consul/docs/lambda/registration/automate#deploy-the-lambda-registrator) for instructions. ## Write the Lambda function code @@ -259,12 +259,12 @@ Define the following environment variables in your Lambda functions to configure | `CONSUL_EXTENSION_DATA_PREFIX` | Specifies the prefix that the plugin pulls configuration data from. The data must be located in the following directory:
    `“${CONSUL_EXTENSION_DATA_PREFIX}/${CONSUL_SERVICE_PARTITION}/${CONSUL_SERVICE_NAMESPACE}/”` | none | | `CONSUL_SERVICE_NAMESPACE` | Specifies the Consul namespace the service is registered into. | `default` | | `CONSUL_SERVICE_PARTITION` | Specifies the Consul partition the service is registered into. | `default` | -| `CONSUL_REFRESH_FREQUENCY` | Specifies the amount of time the extension waits before re-pulling data from the Parameter Store. Use [Go `time.Duration`](https://pkg.go.dev/time@go1.19.1#ParseDuration) string values, for example, `”30s”`.
    The time is added to the duration configured in the Lambda registrator `sync_frequency_in_minutes` configuration. Refer to [Lambda registrator configuration options](/docs/lambda/registration/automate#lambda-registrator-configuration-options). The combined configurations determine how stale the data may become. Lambda functions can run for up to 14 hours, so we recommend configuring a value that results in acceptable staleness for certificates. | `“5m”` | -| `CONSUL_SERVICE_UPSTREAMS` | Specifies a comma-separated list of upstream services that the Lambda function can call. Specify the value as an unlabelled annotation according to the [`consul.hashicorp.com/connect-service-upstreams` annotation format](/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) in Consul on Kubernetes. For example, `"[service-name]:[port]:[optional-datacenter]"` | none | +| `CONSUL_REFRESH_FREQUENCY` | Specifies the amount of time the extension waits before re-pulling data from the Parameter Store. Use [Go `time.Duration`](https://pkg.go.dev/time@go1.19.1#ParseDuration) string values, for example, `”30s”`.
    The time is added to the duration configured in the Lambda registrator `sync_frequency_in_minutes` configuration. Refer to [Lambda registrator configuration options](/consul/docs/lambda/registration/automate#lambda-registrator-configuration-options). The combined configurations determine how stale the data may become. Lambda functions can run for up to 14 hours, so we recommend configuring a value that results in acceptable staleness for certificates. | `“5m”` | +| `CONSUL_SERVICE_UPSTREAMS` | Specifies a comma-separated list of upstream services that the Lambda function can call. Specify the value as an unlabelled annotation according to the [`consul.hashicorp.com/connect-service-upstreams` annotation format](/consul/docs/k8s/annotations-and-labels#consul-hashicorp-com-connect-service-upstreams) in Consul on Kubernetes. For example, `"[service-name]:[port]:[optional-datacenter]"` | none | ## Invoke the Lambda function -If _intentions_ are enabled in the Consul service mesh, you must create an intention that allows the Lambda function's Consul service to invoke all upstream services prior to invoking the Lambda function. Refer to [Service Mesh Intentions](/docs/connect/intentions) for additional information. +If _intentions_ are enabled in the Consul service mesh, you must create an intention that allows the Lambda function's Consul service to invoke all upstream services prior to invoking the Lambda function. Refer to [Service Mesh Intentions](/consul/docs/connect/intentions) for additional information. There are several ways to invoke Lambda functions. In the following example, the `aws lambda invoke` CLI command invokes the function: diff --git a/website/content/docs/lambda/registration/automate.mdx b/website/content/docs/lambda/registration/automate.mdx index 31483a15bc..4614be6950 100644 --- a/website/content/docs/lambda/registration/automate.mdx +++ b/website/content/docs/lambda/registration/automate.mdx @@ -13,7 +13,7 @@ This topic describes how to automate Lambda function registration using Consul's You can deploy the Lambda registrator to your environment to automatically register and deregister Lambda functions with Consul based on the function's tags. Refer to the [AWS Lambda tags documentation](https://docs.aws.amazon.com/lambda/latest/dg/configuration-tags.html) to learn about tags. -The registrator also stores and periodically updates information required to make mTLS requests to upstream services in the AWS parameter store. This enables Lambda functions to invoke mesh services. Refer to [Invoke Services from Lambda Functions](/docs/lambda/invoke-from-lambda) for additional information. +The registrator also stores and periodically updates information required to make mTLS requests to upstream services in the AWS parameter store. This enables Lambda functions to invoke mesh services. Refer to [Invoke Services from Lambda Functions](/consul/docs/lambda/invoke-from-lambda) for additional information. The registrator runs as a Lambda function that is invoked by AWS EventBridge. Refer to the [AWS EventBridge documentation](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-what-is.html) for additional information. @@ -38,7 +38,7 @@ The following diagram shows the flow of events from EventBridge into Consul: ## Requirements -Verify that your environment meets the requirements specified in [Lambda Function Registration Requirements](/docs/lambda/registration). +Verify that your environment meets the requirements specified in [Lambda Function Registration Requirements](/consul/docs/lambda/registration). ## Configuration @@ -46,7 +46,7 @@ The Lambda registrator stores data in the AWS Parameter Store. You can configure ### Optional: Store the CA certificate in Parameter Store -When Lambda registrator makes a request to Consul's [HTTP API](/api-docs) over HTTPS and the Consul API is signed by a custom CA, Lambda registrator uses the CA certificate stored in AWS Parameter Store to verify the authenticity of the Consul API. Refer to the [Parameter Store documentation](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) for additional information. +When Lambda registrator makes a request to Consul's [HTTP API](/consul/api-docs) over HTTPS and the Consul API is signed by a custom CA, Lambda registrator uses the CA certificate stored in AWS Parameter Store to verify the authenticity of the Consul API. Refer to the [Parameter Store documentation](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html) for additional information. You can apply the following Terraform configuration to store Consul's server CA in Parameter Store: @@ -60,7 +60,7 @@ resource "aws_ssm_parameter" "ca-cert" { ### Optional: Store the ACL token in Parameter Store -If [Consul access control lists (ACLs)](/docs/security/acl) are enabled, Lambda registrator must present an ACL token stored in Parameter Store to access resources. You can use the Consul CLI, API, or the Terraform provider to facilitate the ACL workflow. The following procedure describes how to create and store a token from the command line: +If [Consul access control lists (ACLs)](/consul/docs/security/acl) are enabled, Lambda registrator must present an ACL token stored in Parameter Store to access resources. You can use the Consul CLI, API, or the Terraform provider to facilitate the ACL workflow. The following procedure describes how to create and store a token from the command line: 1. Create an ACL policy that includes the following rule: diff --git a/website/content/docs/lambda/registration/index.mdx b/website/content/docs/lambda/registration/index.mdx index c1296bb19e..16e16cde05 100644 --- a/website/content/docs/lambda/registration/index.mdx +++ b/website/content/docs/lambda/registration/index.mdx @@ -56,13 +56,13 @@ Mesh gateways are optional for enabling services to invoke Lambda functions if t The mesh gateway must be running and registered in the relevant Consul datacenters and admin partitions. Refer to the following documentation and tutorials for instructions on how to set up mesh gateways: -- [Mesh gateway documentation](/docs/connect/gateways#mesh-gateways) -- [Connect Services Across Datacenters with Mesh Gateways tutorial](https://learn.hashicorp.com/tutorials/consul/service-mesh-gateways) -- [Secure Service Mesh Communication Across Kubernetes Clusters tutorial](https://learn.hashicorp.com/tutorials/consul/kubernetes-mesh-gateways?utm_source=docs?in=consul/kubernetes) +- [Mesh gateway documentation](/consul/docs/connect/gateways#mesh-gateways) +- [Connect Services Across Datacenters with Mesh Gateways tutorial](/consul/tutorials/developer-mesh/service-mesh-gateways) +- [Secure Service Mesh Communication Across Kubernetes Clusters tutorial](/consul/tutorials/kubernetes/kubernetes-mesh-gateways?utm_source=docs%3Fin%3Dconsul%2Fkubernetes) When using admin partitions, you must add Lambda services to the `Services` field of [the `exported-services` configuration -entry](/docs/connect/config-entries/exported-services). +entry](/consul/docs/connect/config-entries/exported-services). ### Optional: Terminating gateway @@ -70,9 +70,9 @@ A terminating gateway is an access point in a Consul datacenter to an external s Refer to the following documentation and tutorials for instructions on how to set up a terminating gateway: -- [Terminating gateways documentation](/docs/connect/gateways#terminating-gateways) -- [Terminating gateways on Kubernetes documentation](/docs/k8s/connect/terminating-gateways) -- [Connect External Services to Consul With Terminating Gateways tutorial](https://learn.hashicorp.com/tutorials/consul/terminating-gateways-connect-external-services) +- [Terminating gateways documentation](/consul/docs/connect/gateways#terminating-gateways) +- [Terminating gateways on Kubernetes documentation](/consul/docs/k8s/connect/terminating-gateways) +- [Connect External Services to Consul With Terminating Gateways tutorial](/consul/tutorials/developer-mesh/terminating-gateways-connect-external-services) To register a Lambda service with a terminating gateway, add the service to the `Services` field of the terminating gateway's `terminating-gateway` diff --git a/website/content/docs/lambda/registration/manual.mdx b/website/content/docs/lambda/registration/manual.mdx index 45019839c7..fbb07dba36 100644 --- a/website/content/docs/lambda/registration/manual.mdx +++ b/website/content/docs/lambda/registration/manual.mdx @@ -7,13 +7,13 @@ description: >- # Manual Lambda Function Registration -This topic describes how to manually register Lambda functions into Consul. Refer to [Automate Lambda Function Registration](/docs/lambda/registration/automate) for information about using the Lambda registrator to automate registration. +This topic describes how to manually register Lambda functions into Consul. Refer to [Automate Lambda Function Registration](/consul/docs/lambda/registration/automate) for information about using the Lambda registrator to automate registration. ## Requirements -Verify that your environment meets the requirements specified in [Lambda Function Registration Requirements](/docs/lambda/registration). +Verify that your environment meets the requirements specified in [Lambda Function Registration Requirements](/consul/docs/lambda/registration). -To manually register Lambda functions so that mesh services can invoke them, you must create and apply a service registration configuration for the Lambda function and write a [service defaults configuration entry](/docs/connect/config-entries/service-defaults) for the function. +To manually register Lambda functions so that mesh services can invoke them, you must create and apply a service registration configuration for the Lambda function and write a [service defaults configuration entry](/consul/docs/connect/config-entries/service-defaults) for the function. ## Register a Lambda function diff --git a/website/content/docs/nia/api/index.mdx b/website/content/docs/nia/api/index.mdx index 07b1d396e6..2e0cf3d840 100644 --- a/website/content/docs/nia/api/index.mdx +++ b/website/content/docs/nia/api/index.mdx @@ -11,7 +11,7 @@ Consul-Terraform-Sync (CTS) provides an HTTP API interface for querying CTS inst ## Port -The API is served at the default port `8558` or a different port if set with [`port` configuration](/docs/nia/configuration#port) +The API is served at the default port `8558` or a different port if set with [`port` configuration](/consul/docs/nia/configuration#port) ## Version prefix @@ -27,4 +27,4 @@ Each call to a CTS API endpoint returns a `request_id` field. The field is a str ## Error messages -The API sends a response code in the 200 range if the call is successful. If the call is unsuccessful, the API sends an error message that includes additional information when possible. Refer to [Error Messages](/docs/nia/usage/errors-ref) for additional information. \ No newline at end of file +The API sends a response code in the 200 range if the call is successful. If the call is unsuccessful, the API sends an error message that includes additional information when possible. Refer to [Error Messages](/consul/docs/nia/usage/errors-ref) for additional information. \ No newline at end of file diff --git a/website/content/docs/nia/api/status.mdx b/website/content/docs/nia/api/status.mdx index 108f2c9aa0..98f4667206 100644 --- a/website/content/docs/nia/api/status.mdx +++ b/website/content/docs/nia/api/status.mdx @@ -6,9 +6,9 @@ description: >- --- # Status -The `/status` endpoints return status-related information for tasks. This endpoint returns a count of successful and failed task events that are recorded whenever tasks execute an automation. Currently, only the five most recent events are stored in Consul-Terraform-Sync (CTS). For more information on the hierarchy of status information and how it is collected, refer to [Status Information](/docs/nia/tasks#status-information). +The `/status` endpoints return status-related information for tasks. This endpoint returns a count of successful and failed task events that are recorded whenever tasks execute an automation. Currently, only the five most recent events are stored in Consul-Terraform-Sync (CTS). For more information on the hierarchy of status information and how it is collected, refer to [Status Information](/consul/docs/nia/tasks#status-information). -If CTS is configured [for high availability](/docs/nia/usage/run-ha), you can send requests to the [`/status/cluster` endpoint path](#cluster-status) on any CTS cluster member instance to receive information about the entire cluster. Calling the `status` endpoint path (without `/cluster`), however, returns a 400 error if the request is sent to a follower instance. The error message depends on what information the follower instance is able to obtain about the leader. Refer to [Error Messages](/docs/nia/usage/errors-ref) for more information. +If CTS is configured [for high availability](/consul/docs/nia/usage/run-ha), you can send requests to the [`/status/cluster` endpoint path](#cluster-status) on any CTS cluster member instance to receive information about the entire cluster. Calling the `status` endpoint path (without `/cluster`), however, returns a 400 error if the request is sent to a follower instance. The error message depends on what information the follower instance is able to obtain about the leader. Refer to [Error Messages](/consul/docs/nia/usage/errors-ref) for more information. ## Status for all tasks @@ -68,7 +68,7 @@ Response: This endpoint returns the individual task status information for a single specified task or for all tasks. -Task health status value is determined by the success or failure of all stored [event data](/docs/nia/tasks#event) on the process of updating network infrastructure for a task. Currently only the 5 most recent events are stored per task. +Task health status value is determined by the success or failure of all stored [event data](/consul/docs/nia/tasks#event) on the process of updating network infrastructure for a task. Currently only the 5 most recent events are stored per task. - Successful: The most recent stored event is successful. - Errored: The most recent stored event is not successful but all previous stored events are successful. - Critical: The most recent stored event is not successful and one or more previous stored events are also not successful. @@ -103,11 +103,11 @@ The response is a JSON map of task name to a status information structure with t |`services` | list[string] | **Deprecated in CTS 0.5.0 and will be removed in a future major release.** List of the services configured for the task. |`providers` | list[string] | **Deprecated in CTS 0.5.0 and will be removed in v0.8.0.** List of the providers configured for the task. |`events_url` | string | Relative URL to retrieve the event data stored for the task. -|`events` | list[[Event](/docs/nia/api/status#event)] | List of stored events that inform the task's status. See [section below](/docs/nia/api/status#event) for information on event data. This field is only included in the response upon request by setting the `?include=events` parameter. The relative URL for the request to include events can be retrieved from the `events_url` field. +|`events` | list[[Event](/consul/docs/nia/api/status#event)] | List of stored events that inform the task's status. See [section below](/consul/docs/nia/api/status#event) for information on event data. This field is only included in the response upon request by setting the `?include=events` parameter. The relative URL for the request to include events can be retrieved from the `events_url` field. #### Event -Event represents the process of updating network infrastructure of a task. The data is captured in a JSON structure. For more details on the scope of an event, see [Event](/docs/nia/tasks#event). +Event represents the process of updating network infrastructure of a task. The data is captured in a JSON structure. For more details on the scope of an event, see [Event](/consul/docs/nia/tasks#event). | Name | Type | Description | | ----------- | ------ | ------------------ | @@ -229,7 +229,7 @@ Response: ## Cluster status -The `/v1/status/cluster` API endpoint returns information about high-availability clusters and its members, such as health status and leadership. This endpoint is only supported when using CTS in [high availability mode](/docs/nia/usage/run-ha). If you call the endpoint without configuring CTS for high availability, then CTS prints an error to the console. Refer to [Error Messages](/docs/nia/usage/errors-ref) for information about CTS error messages. +The `/v1/status/cluster` API endpoint returns information about high-availability clusters and its members, such as health status and leadership. This endpoint is only supported when using CTS in [high availability mode](/consul/docs/nia/usage/run-ha). If you call the endpoint without configuring CTS for high availability, then CTS prints an error to the console. Refer to [Error Messages](/consul/docs/nia/usage/errors-ref) for information about CTS error messages. | Method | Path | Response format | | ------ | ----------------- | ------------------ | @@ -258,11 +258,11 @@ The following table describes the fields available for objects in the `members` | Field | Type | Description | | --- | ---- | --- | -| `address` | string | Indicates the location of the instance. The address is only included in the response if the `high_availability.instance.address` option is configured on the leader instance. Refer to the [high availability instance configuration](/docs/nia/configuration#high-availability-instance) reference for additional information. | -| `healthy` | boolean | Indicates the health of the service instance health. Refer to [Service Registration](/docs/nia/configuration#service-registration) for additional information. | -| `id` | string | Indicates the service registration ID. Refer to [Service Registration](/docs/nia/configuration#service-registration) for additional information. | +| `address` | string | Indicates the location of the instance. The address is only included in the response if the `high_availability.instance.address` option is configured on the leader instance. Refer to the [high availability instance configuration](/consul/docs/nia/configuration#high-availability-instance) reference for additional information. | +| `healthy` | boolean | Indicates the health of the service instance health. Refer to [Service Registration](/consul/docs/nia/configuration#service-registration) for additional information. | +| `id` | string | Indicates the service registration ID. Refer to [Service Registration](/consul/docs/nia/configuration#service-registration) for additional information. | | `leader` | boolean | Identifies the cluster leader. | -| `service_name` | string | Identifies the name of the service that the instance represents. The value is set by the `service_name` field in the [Service Registration](/docs/nia/configuration#service-registration) configuration. | +| `service_name` | string | Identifies the name of the service that the instance represents. The value is set by the `service_name` field in the [Service Registration](/consul/docs/nia/configuration#service-registration) configuration. | ### Example diff --git a/website/content/docs/nia/api/tasks.mdx b/website/content/docs/nia/api/tasks.mdx index 60ca787a3b..1f5ca51404 100644 --- a/website/content/docs/nia/api/tasks.mdx +++ b/website/content/docs/nia/api/tasks.mdx @@ -9,7 +9,7 @@ description: >- The `/tasks` endpoints interact with the tasks that Consul-Terraform-Sync (CTS) is responsible for running. -If you [run CTS with high availability enabled](/docs/nia/usage/run-ha), you can send requests to the `/tasks` endpoint on CTS leader or follower instances. Requests to a follower instance, however, return a 400 Bad Request and error message. The error message depends on what information the follower instance is able to obtain about the leader. Refer to [Error Messages](/docs/nia/usage/errors-ref) for more information. +If you [run CTS with high availability enabled](/consul/docs/nia/usage/run-ha), you can send requests to the `/tasks` endpoint on CTS leader or follower instances. Requests to a follower instance, however, return a 400 Bad Request and error message. The error message depends on what information the follower instance is able to obtain about the leader. Refer to [Error Messages](/consul/docs/nia/usage/errors-ref) for more information. ## Get Tasks @@ -30,7 +30,7 @@ This endpoint returns information about all existing tasks. | Name | Type | Description | | ------------ | ------------- | ---------------------------------------------------------------------------------- | | `request_id` | string | The ID of the request. Used for auditing and debugging purposes. | -| `tasks` | list[[Task](/docs/nia/api/tasks#task-object)] | A list of Tasks | +| `tasks` | list[[Task](/consul/docs/nia/api/tasks#task-object)] | A list of Tasks | ### Example: Retrieve all tasks @@ -253,7 +253,7 @@ Response: ## Update Task -This endpoint allows patch updates to specifically supported fields for existing tasks. Currently only supports updating a task's [`enabled` value](/docs/nia/configuration#enabled-7). +This endpoint allows patch updates to specifically supported fields for existing tasks. Currently only supports updating a task's [`enabled` value](/consul/docs/nia/configuration#enabled-7). | Method | Path | Produces | | ------- | ------------------- | ------------------ | @@ -283,7 +283,7 @@ This endpoint allows patch updates to specifically supported fields for existing | Name | Type | Description | | ------------------------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `inspect` | object | Information on how resources would be changed given a proposed task update, similar to [inspect-mode](/docs/nia/cli/#inspect-mode). This is only returned when passed the `run=inspect` request parameter. | +| `inspect` | object | Information on how resources would be changed given a proposed task update, similar to [inspect-mode](/consul/docs/nia/cli/#inspect-mode). This is only returned when passed the `run=inspect` request parameter. | | `inspect.changes_present` | boolean | Whether or not changes were detected for running the proposed task update. | | `inspect.plan` | string | The Terraform plan generated for the proposed task update. Note: a non-empty string does not necessarily indicate changes were detected. | @@ -383,7 +383,7 @@ $ curl --request DELETE \ ## Task Object -The task object is used by the Task APIs as part of a request or response. It represents the task's [configuration information](/docs/nia/configuration#task). +The task object is used by the Task APIs as part of a request or response. It represents the task's [configuration information](/consul/docs/nia/configuration#task). | Name | Required | Type | Description | Default | | ----------------------- | ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | @@ -391,14 +391,14 @@ The task object is used by the Task APIs as part of a request or response. It re | `buffer_period.enabled` | bool | Optional | Whether the buffer period is enabled or disabled. | The global buffer period's enabled value configured for CTS. | | `buffer_period.min` | string | Optional | The minimum period of time to wait after changes are detected before triggering the task. | The global buffer period's min value configured for CTS. | | `buffer_period.max` | string | Optional | The maximum period of time to wait after changes are detected before triggering the task. | The global buffer period's max value configured for CTS. | -| `condition` | object | Required | The [condition](/docs/nia/configuration#task-condition) on which to trigger the task to execute.

    If the task has the deprecated `services` field configured as a module input, it is represented here as `condition.services`. | none | +| `condition` | object | Required | The [condition](/consul/docs/nia/configuration#task-condition) on which to trigger the task to execute.

    If the task has the deprecated `services` field configured as a module input, it is represented here as `condition.services`. | none | | `description` | string | Optional | The human readable text to describe the task. | none | | `enabled` | bool | Optional | Whether the task is enabled or disabled from executing. | `true` | | `module` | string | Required | The location of the Terraform module. | none | -| `module_input` | object | Optional | The additional [module input(s)](/docs/nia/configuration#task-source-input) that the tasks provides to the Terraform module on execution.

    If the task has the deprecated `services` field configured as a module input, it is represented here as `module_input.services`. | none | +| `module_input` | object | Optional | The additional [module input(s)](/consul/docs/nia/configuration#task-source-input) that the tasks provides to the Terraform module on execution.

    If the task has the deprecated `services` field configured as a module input, it is represented here as `module_input.services`. | none | | `name` | string | Required | The unique name of the task. | none | | `providers` | list[string] | Optional | The list of provider names that the task's module uses. | none | | `variables` | map[string] | Optional | The map of variables that are provided to the task's module. | none | | `version` | string | Optional | The version of the configured module that the task uses. | The latest version. | -| `terraform_version` | string | Optional | **Deprecated in CTS 0.6.0 and will be removed in 0.8.0. Review `terraform_version` in `terraform_cloud_workspace` instead.** The version of Terraform to use for the Terraform Cloud workspace associated with the task. This is only available when used with the [Terraform Cloud driver](/docs/nia/configuration#terraform-cloud-driver). | The latest compatible version supported by the organization. | -| `terraform_cloud_workspace` | object | Optional | The [configurable attributes of the Terraform Cloud workspace](/docs/nia/configuration#terraform_cloud_workspace) associated with the task. This option is only available when used with the [Terraform Cloud driver](/docs/nia/configuration#terraform-cloud-driver).| none | +| `terraform_version` | string | Optional | **Deprecated in CTS 0.6.0 and will be removed in 0.8.0. Review `terraform_version` in `terraform_cloud_workspace` instead.** The version of Terraform to use for the Terraform Cloud workspace associated with the task. This is only available when used with the [Terraform Cloud driver](/consul/docs/nia/configuration#terraform-cloud-driver). | The latest compatible version supported by the organization. | +| `terraform_cloud_workspace` | object | Optional | The [configurable attributes of the Terraform Cloud workspace](/consul/docs/nia/configuration#terraform_cloud_workspace) associated with the task. This option is only available when used with the [Terraform Cloud driver](/consul/docs/nia/configuration#terraform-cloud-driver).| none | diff --git a/website/content/docs/nia/architecture.mdx b/website/content/docs/nia/architecture.mdx index 8d564c9ace..1519bc82cb 100644 --- a/website/content/docs/nia/architecture.mdx +++ b/website/content/docs/nia/architecture.mdx @@ -22,7 +22,7 @@ The following diagram shows the CTS workflow as it monitors the Consul service c ## Watcher and views -CTS uses Consul’s [blocking queries](/api-docs/features/blocking) functionality to monitor Consul for updates. If an endpoint does not support blocking queries, CTS uses polling to watch for changes. These mechanisms are referred to in CTS as *watchers*. +CTS uses Consul’s [blocking queries](/consul/api-docs/features/blocking) functionality to monitor Consul for updates. If an endpoint does not support blocking queries, CTS uses polling to watch for changes. These mechanisms are referred to in CTS as *watchers*. The watcher maintains a separate thread for each value monitored and runs any tasks that depend on the watched value whenever it is updated. These threads are referred to as _views_. For example, a thread may run a task to update a proxy when the watcher detects that an instance has become unhealthy . @@ -38,12 +38,12 @@ discovered IP addresses for a set of Consul services. ## Drivers A driver encapsulates the resources required to communicate the updates to the -network infrastructure. The following [drivers](/docs/nia/network-drivers#terraform) are supported: +network infrastructure. The following [drivers](/consul/docs/nia/network-drivers#terraform) are supported: - Terraform driver - Terraform Cloud driver -Each driver includes a set of providers that [enables support](/docs/nia/terraform-modules) for a wide variety of infrastructure applications. +Each driver includes a set of providers that [enables support](/consul/docs/nia/terraform-modules) for a wide variety of infrastructure applications. ## State storage and persistence @@ -51,29 +51,29 @@ The following types of state information are associated with CTS. ### Terraform state information -By default, CTS stores [Terraform state data](https://www.terraform.io/language/state) in the Consul KV, but you can specify where this information is stored by configuring the `backend` setting in the [Terraform driver configuration](/docs/nia/configuration#backend). The data persists if CTS stops and the backend is configured to a remote location. +By default, CTS stores [Terraform state data](/terraform/language/state) in the Consul KV, but you can specify where this information is stored by configuring the `backend` setting in the [Terraform driver configuration](/consul/docs/nia/configuration#backend). The data persists if CTS stops and the backend is configured to a remote location. ### CTS task and event data -By default, CTS stores task and event data in memory. This data is transient and does not persist. If you configure [CTS to run with high availability enabled](/docs/nia/usage/run-ha), CTS stores the data in the Consul KV. High availability is an enterprise feature that promotes CTS resiliency. When high availability is enabled, CTS stores and persists task changes and events that occur when an instance stops. +By default, CTS stores task and event data in memory. This data is transient and does not persist. If you configure [CTS to run with high availability enabled](/consul/docs/nia/usage/run-ha), CTS stores the data in the Consul KV. High availability is an enterprise feature that promotes CTS resiliency. When high availability is enabled, CTS stores and persists task changes and events that occur when an instance stops. -The data stored when operating in high availability mode includes task changes made using the task API or CLI. Examples of task changes include creating a new task, deleting a task, and enabling or disabling a task. You can empty the leader’s stored state information by starting CTS with the [`-reset-storage` flag](/docs/nia/cli/start#options). +The data stored when operating in high availability mode includes task changes made using the task API or CLI. Examples of task changes include creating a new task, deleting a task, and enabling or disabling a task. You can empty the leader’s stored state information by starting CTS with the [`-reset-storage` flag](/consul/docs/nia/cli/start#options). ## Instance compatibility checks (high availability) -If you [run CTS with high availability enabled](/docs/nia/usage/run-ha), CTS performs instance compatibility checks to ensure that all instances in the cluster behave consistently. Consistent instance behavior enables CTS to properly perform automations configured in the state storage. +If you [run CTS with high availability enabled](/consul/docs/nia/usage/run-ha), CTS performs instance compatibility checks to ensure that all instances in the cluster behave consistently. Consistent instance behavior enables CTS to properly perform automations configured in the state storage. -The CTS instance compatibility check reports an error if the task [module](/docs/nia/configuration#module) is configured with a local module, but the module does not exist on the CTS instance. Refer to the [Terraform documentation](https://www.terraform.io/language/modules/sources#module-sources) for additional information about module sources. Example log: +The CTS instance compatibility check reports an error if the task [module](/consul/docs/nia/configuration#module) is configured with a local module, but the module does not exist on the CTS instance. Refer to the [Terraform documentation](/terraform/language/modules/sources#module-sources) for additional information about module sources. Example log: ```shell-session [ERROR] ha.compat: error="compatibility check failure: stat ./example-module: no such file or directory" ``` -Refer to [Error Messages](/docs/nia/usage/errors-ref) for additional information. +Refer to [Error Messages](/consul/docs/nia/usage/errors-ref) for additional information. CTS instances perform a compatibility check on start-up based on the stored state and every five minutes after starting. If the check detects an incompatible CTS instance, it generates a log so that an operator can address it. -CTS logs the error message and continues to run when it finds an incompatibility. CTS can still elect an incompatible instance to be the leader, but tasks affected by the incompatibility do not run successfully. This can happen when all active CTS instances enter [`once-mode`](/docs/nia/cli/start#modes) and run the tasks once when initially elected. +CTS logs the error message and continues to run when it finds an incompatibility. CTS can still elect an incompatible instance to be the leader, but tasks affected by the incompatibility do not run successfully. This can happen when all active CTS instances enter [`once-mode`](/consul/docs/nia/cli/start#modes) and run the tasks once when initially elected. ## Security guidelines -We recommend following the network security guidelines described in the [Secure Consul-Terraform-Sync for Production](https://learn.hashicorp.com/tutorials/consul/consul-terraform-sync-secure?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. The tutorial contains a checklist of best practices to secure your CTS installation for a production environment. +We recommend following the network security guidelines described in the [Secure Consul-Terraform-Sync for Production](/consul/tutorials/network-infrastructure-automation/consul-terraform-sync-secure?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. The tutorial contains a checklist of best practices to secure your CTS installation for a production environment. diff --git a/website/content/docs/nia/cli/index.mdx b/website/content/docs/nia/cli/index.mdx index c8a6292438..9e338819da 100644 --- a/website/content/docs/nia/cli/index.mdx +++ b/website/content/docs/nia/cli/index.mdx @@ -11,7 +11,7 @@ Consul-Terraform-Sync (CTS) is controlled via an easy to use command-line interf ## Daemon -~> Running CTS as a daemon without using a command is deprecated in CTS 0.6.0 and will be removed at a much later date in a major release. For information on the preferred way to run CTS as a daemon review the [`start` command docs](/docs/nia/cli/start) +~> Running CTS as a daemon without using a command is deprecated in CTS 0.6.0 and will be removed at a much later date in a major release. For information on the preferred way to run CTS as a daemon review the [`start` command docs](/consul/docs/nia/cli/start) When CTS runs as a daemon, there is no default configuration to start CTS. You must set a configuration flag -config-file or -config-dir. For example: @@ -89,5 +89,5 @@ Below are options that can be used across all commands: | `-ssl-verify` | Optional | boolean | Enables verification for TLS/SSL connections to the API if set to true. This does not affect insecure HTTP connections.

    Alternatively, you can specify the value using the `CTS_SSL_VERIFY` environment variable. | `true` | | `-ca-cert` | Optional | string | Path to a PEM-encoded certificate authority file that is used to verify TLS/SSL connections. Takes precedence over `-ca-path` if both are provided.

    Alternatively, you can specify the value using the `CTS_CACERT` environment variable. | none | | `-ca-path` | Optional | string | Path to a directory containing a PEM-encoded certificate authority file that is used to verify TLS/SSL connections.

    Alternatively, you can specify the value using the `CTS_CAPATH` environment variable. | none | -| `-client-cert`                                                   | Optional | string | Path to a PEM-encoded client certificate that the CTS API requires when [`verify_incoming`](/docs/nia/configuration#verify_incoming) is set to `true` on the API.

    Alternatively, you can specify the value using the `CTS_CLIENT_CERT` environment variable. | none | -| `-client-key` | Optional | string | Path to a PEM-encoded client key for the certificate configured with the `-client-cert` option. This is required if `-client-cert` is set and if [`verify_incoming`](/docs/nia/configuration#verify_incoming) is set to `true` on the CTS API.

    Alternatively, you can specify the value using the `CTS_CLIENT_KEY` environment variable. | none | +| `-client-cert`                                                   | Optional | string | Path to a PEM-encoded client certificate that the CTS API requires when [`verify_incoming`](/consul/docs/nia/configuration#verify_incoming) is set to `true` on the API.

    Alternatively, you can specify the value using the `CTS_CLIENT_CERT` environment variable. | none | +| `-client-key` | Optional | string | Path to a PEM-encoded client key for the certificate configured with the `-client-cert` option. This is required if `-client-cert` is set and if [`verify_incoming`](/consul/docs/nia/configuration#verify_incoming) is set to `true` on the CTS API.

    Alternatively, you can specify the value using the `CTS_CLIENT_KEY` environment variable. | none | diff --git a/website/content/docs/nia/cli/start.mdx b/website/content/docs/nia/cli/start.mdx index c47a183df6..68b3f6bd7a 100644 --- a/website/content/docs/nia/cli/start.mdx +++ b/website/content/docs/nia/cli/start.mdx @@ -15,7 +15,7 @@ The `start` command starts the Consul-Terraform-Sync (CTS) daemon. $ consul-terraform-sync start -config-file [OPTIONS] ``` -The `-config-file` or `-config-dir` flag is required. Use the flag to specify the [CTS instance configuration file](/docs/nia/configuration) or directory containing several configuration files to start a CTS cluster. +The `-config-file` or `-config-dir` flag is required. Use the flag to specify the [CTS instance configuration file](/consul/docs/nia/configuration) or directory containing several configuration files to start a CTS cluster. ## Options @@ -28,7 +28,7 @@ The following table describes all of the available flags. | `-inspect` | Optional | boolean | Starts CTS in inspect mode . In inspect mode, CTS displays the proposed state changes for all tasks once and exits. No changes are applied. Refer to [Modes](#modes) for additional information. If an error occurs before displaying all changes, CTS exits with a non-zero status. | `false` | | `-inspect-task` | Optional | string | Starts CTS in inspect mode for the specified task. CTS displays the proposed state changes for the specified task and exits. No changes are applied.
    You can specify the flag multiple times to display more than one task.
    If an error occurs before displaying all changes, CTS exits with a non-zero status. | none | | `-once` | Optional | boolean | Starts CTS in once-mode. In once-mode, CTS renders templates, runs tasks once, and disables buffer periods. Refer to [Modes](#modes) for additional information. | `false` | -| `-reset-storage` | Optional | boolean | Directs CTS to overwrite the state storage with new state information when the instance you are starting is elected the cluster leader.
    Only use this flag when running CTS in [high availability mode](/docs/nia/usage/run-ha). | `false` | +| `-reset-storage` | Optional | boolean | Directs CTS to overwrite the state storage with new state information when the instance you are starting is elected the cluster leader.
    Only use this flag when running CTS in [high availability mode](/consul/docs/nia/usage/run-ha). | `false` | | `-h`, `-help` | Optional | boolean | Prints the CTS command line help. | `false` | ## Modes @@ -40,4 +40,4 @@ By default, CTS starts in long-running mode. The following table describes all a | Long-running mode | CTS starts in once-mode and switches to a long-running process.

    During the once-mode phase, the daemon exits with a non-zero status if it encounters an error.

    After successfully operating in once-mode, CTS begins a long-running process.

    When the long-running process begins, the CTS daemon serves API and command requests.

    If an error occurs, CTS logs it and continues running.

    | No additional flags.
    This is the default mode. | | Once-mode | In once-mode, CTS renders templates and runs tasks once. CTS does not start the process in long-running mode and disables buffer periods.

    Use once-mode before starting CTS in long-running mode to verify that your configuration is accurate and tasks update network infrastructure as expected.

    | Add the `-once` flag when starting CTS. | | Inspect mode | CTS displays the proposed state changes for all tasks once and exits. No changes are applied. If an error occurs before displaying all changes, CTS exits with a non-zero status.

    Use inspect mode before starting CTS in long-running mode to debug one or more tasks and to verify that your tasks will update network infrastructure as expected.

    | Add the `-inspect` flag to verify all tasks.

    Add the `-inspect-task` flag to inspect a single task. Use multiple flags to verify more than one task.

    | -| High availability mode | A long-running process that ensures that all changes to Consul that occur during a failover transition are processed and that CTS continues to operate as expected. CTS logs the errors and continues to operate without interruption. Refer to [Run Consul-Terraform-Sync with High Availability](/docs/nia/usage/run-ha) for additional information. | Add the `high_availability` block to your CTS instance configuration.

    Refer to [Run Consul-Terraform-Sync with High Availability](/docs/nia/usage/run-ha) for additional information.

    | +| High availability mode | A long-running process that ensures that all changes to Consul that occur during a failover transition are processed and that CTS continues to operate as expected. CTS logs the errors and continues to operate without interruption. Refer to [Run Consul-Terraform-Sync with High Availability](/consul/docs/nia/usage/run-ha) for additional information. | Add the `high_availability` block to your CTS instance configuration.

    Refer to [Run Consul-Terraform-Sync with High Availability](/consul/docs/nia/usage/run-ha) for additional information.

    | diff --git a/website/content/docs/nia/cli/task.mdx b/website/content/docs/nia/cli/task.mdx index b4316f5dbf..ea10591848 100644 --- a/website/content/docs/nia/cli/task.mdx +++ b/website/content/docs/nia/cli/task.mdx @@ -9,7 +9,7 @@ description: >- ## task create -`task create` command creates a new task so that it will run and update task resources. The command generates and outputs a Terraform plan, similar to [inspect-mode](/docs/nia/cli/start#modes), of how resources will be modified if the task is created. The command will then ask for user approval before creating the task. +`task create` command creates a new task so that it will run and update task resources. The command generates and outputs a Terraform plan, similar to [inspect-mode](/consul/docs/nia/cli/start#modes), of how resources will be modified if the task is created. The command will then ask for user approval before creating the task. It is not to be used for updating a task and will not create a task if the task name already exists. @@ -19,11 +19,11 @@ It is not to be used for updating a task and will not create a task if the task **Options:** -In addition to [general options](/docs/nia/cli#general-options) this command also supports the following: +In addition to [general options](/consul/docs/nia/cli#general-options) this command also supports the following: | Name | Required | Type | Description | | ------------ | -------- | ------ | ------------------------------------------------------------------------------------------------------------------- | -| `-task-file` | Required | string | The path to the task configuration file. See [configuration information](/docs/nia/configuration#task) for details. | +| `-task-file` | Required | string | The path to the task configuration file. See [configuration information](/consul/docs/nia/configuration#task) for details. | | `-auto-approve`   | Optional | boolean | Whether to skip the interactive approval of the plan before creating. | ### Example @@ -91,7 +91,7 @@ Enter a value: yes ## task enable -`task enable` command enables an existing task so that it will run and update task resources. If the task is already enabled, it will return a success. The command generates and outputs a Terraform plan, similar to [inspect-mode](/docs/nia/cli#inspect-mode), of how resources will be modified if task becomes enabled. If resources changes are detected, the command will ask for user approval before enabling the task. If no resources are detected, the command will go ahead and enable the task. +`task enable` command enables an existing task so that it will run and update task resources. If the task is already enabled, it will return a success. The command generates and outputs a Terraform plan, similar to [inspect-mode](/consul/docs/nia/cli#inspect-mode), of how resources will be modified if task becomes enabled. If resources changes are detected, the command will ask for user approval before enabling the task. If no resources are detected, the command will go ahead and enable the task. ### Usage @@ -105,7 +105,7 @@ Enter a value: yes **Options:** -In addition to [general options](/docs/nia/cli/#general-options) this command also supports the following: +In addition to [general options](/consul/docs/nia/cli/#general-options) this command also supports the following: | Name | Required | Type | Description | | --------------- | -------- | ------- | ------------------------------- | @@ -158,7 +158,7 @@ Enter a value: yes | ----------- | -------- | ------ | -------------------------------- | | `task_name` | Required | string | The name of the task to disable. | -**Options:** Currently only supporting [general options](/docs/nia/cli#general-options) +**Options:** Currently only supporting [general options](/consul/docs/nia/cli#general-options) ### Example @@ -187,7 +187,7 @@ $ consul-terraform-sync task disable task_b **Options:** -In addition to [general options](/docs/nia/cli#general-options) this command also supports the following: +In addition to [general options](/consul/docs/nia/cli#general-options) this command also supports the following: | Name | Required | Type | Description | | --------------- | -------- | ------- | ------------------------------- | diff --git a/website/content/docs/nia/configuration.mdx b/website/content/docs/nia/configuration.mdx index 78110b736f..4d4e8113f8 100644 --- a/website/content/docs/nia/configuration.mdx +++ b/website/content/docs/nia/configuration.mdx @@ -57,7 +57,7 @@ tls { - `verify_incoming` - (bool: false) Enable mutual TLS. Requires all incoming connections to the CTS API to use a TLS connection and provide a certificate signed by a Certificate Authority specified by the `ca_cert` or `ca_path`. - `ca_cert` - (string) The path to a PEM-encoded certificate authority file used to verify the authenticity of the incoming client connections to the CTS API when `verify_incoming` is set to true. Takes precedence over `ca_path` if both are configured. - `ca_path` - (string) The path to a directory of PEM-encoded certificate authority files used to verify the authenticity of the incoming client connections to the CTS API when `verify_incoming` is set to true. -- `license_path` - (string) **Deprecated in CTS 0.6.0 and will be removed in a future release. Use [license block](/docs/nia/configuration#license) instead.** Configures the path to the file that contains the license. You must specify a license in order to use enterprise features. You can also set the license by defining the `CONSUL_LICENSE` and `CONSUL_LICENSE_PATH` environment variables. For more information, refer to [Setting the License](/docs/nia/enterprise/license#setting-the-license). +- `license_path` - (string) **Deprecated in CTS 0.6.0 and will be removed in a future release. Use [license block](/consul/docs/nia/configuration#license) instead.** Configures the path to the file that contains the license. You must specify a license in order to use enterprise features. You can also set the license by defining the `CONSUL_LICENSE` and `CONSUL_LICENSE_PATH` environment variables. For more information, refer to [Setting the License](/consul/docs/nia/enterprise/license#setting-the-license). ## License @@ -78,13 +78,13 @@ license { | Parameter | Required | Type | Description | Default | | --------- | -------- | ---- | ----------- | ------- | -| `path` | Optional | string | Configures the path to the file containing a license. If a path to a license is configured, this license is used until you enable automatic license retrieval. You can also set the license by defining the `CONSUL_LICENSE` and `CONSUL_LICENSE_PATH` environment variables. To learn more, review [Setting the License](/docs/nia/enterprise/license#setting-the-license). | none | -| `auto_retrieval` | Optional | object | Configures the license auto-retrieval used by CTS. To learn more, review [Auto-Retrieval](/docs/nia/configuration#auto-retrieval) for details | Review [Auto-Retrieval](/docs/nia/configuration#auto-retrieval) for defaults. | +| `path` | Optional | string | Configures the path to the file containing a license. If a path to a license is configured, this license is used until you enable automatic license retrieval. You can also set the license by defining the `CONSUL_LICENSE` and `CONSUL_LICENSE_PATH` environment variables. To learn more, review [Setting the License](/consul/docs/nia/enterprise/license#setting-the-license). | none | +| `auto_retrieval` | Optional | object | Configures the license auto-retrieval used by CTS. To learn more, review [Auto-Retrieval](/consul/docs/nia/configuration#auto-retrieval) for details | Review [Auto-Retrieval](/consul/docs/nia/configuration#auto-retrieval) for defaults. | ### Auto-retrieval -You can use the `auto_retrieval` block to configure the the automatic license retrieval in CTS. When enabled, CTS attempts to retrieve a new license from its configured Consul Enterprise backend once a day. If CTS cannot retrieve a license and the current license is reaching its expiration date, CTS attempts to retrieve a license with increased frequency, as defined by the [License Expiration Date Handling](/docs/nia/enterprise/license#license-expiration-handling). +You can use the `auto_retrieval` block to configure the the automatic license retrieval in CTS. When enabled, CTS attempts to retrieve a new license from its configured Consul Enterprise backend once a day. If CTS cannot retrieve a license and the current license is reaching its expiration date, CTS attempts to retrieve a license with increased frequency, as defined by the [License Expiration Date Handling](/consul/docs/nia/enterprise/license#license-expiration-handling). ~> Enabling `auto_retrieval` is recommended when using HCP Consul, as HCP Consul licenses expire more frequently than Consul Enterprise licenses. Without auto-retrieval enabled, you have to restart CTS every time you load a new license. @@ -96,9 +96,9 @@ You can use the `auto_retrieval` block to configure the the automatic license re The `consul` block configures the CTS connection with a Consul agent so that CTS can perform queries for task execution. It also configures the automatic registration of CTS as a service with Consul. --> **Note:** Use HTTP/2 to improve Consul-Terraform-Sync performance when communicating with the local Consul process. [TLS/HTTPS](/docs/agent/config/config-files) must be configured for the local Consul with the [cert_file](/docs/agent/config/config-files#cert_file) and [key_file](/docs/agent/config/config-files#key_file) parameters set. For the Consul-Terraform-Sync configuration, set `tls.enabled = true` and set the `address` parameter to the HTTPS URL, e.g., `address = example.consul.com:8501`. If using self-signed certificates for Consul, you will also need to set `tls.verify = false` or add the certificate to `ca_cert` or `ca_path`. +-> **Note:** Use HTTP/2 to improve Consul-Terraform-Sync performance when communicating with the local Consul process. [TLS/HTTPS](/consul/docs/agent/config/config-files) must be configured for the local Consul with the [cert_file](/consul/docs/agent/config/config-files#cert_file) and [key_file](/consul/docs/agent/config/config-files#key_file) parameters set. For the Consul-Terraform-Sync configuration, set `tls.enabled = true` and set the `address` parameter to the HTTPS URL, e.g., `address = example.consul.com:8501`. If using self-signed certificates for Consul, you will also need to set `tls.verify = false` or add the certificate to `ca_cert` or `ca_path`. -To read more on suggestions for configuring the Consul agent, see [run an agent](/docs/nia/usage/requirements#run-an-agent). +To read more on suggestions for configuring the Consul agent, see [run an agent](/consul/docs/nia/usage/requirements#run-an-agent). ```hcl consul { @@ -121,14 +121,14 @@ consul { | Parameter | Required | Type | Description | Default | | --------- | -------- | ---- | ----------- | ------- | | `address` | Optional | string | The address of the Consul agent. It may be an IP or FQDN. | `localhost:8500` | -| `token` | Optional | string | The ACL token to use for client communication with the local Consul agent. See [ACL Requirements](/docs/nia/configuration#acl-requirements) for required privileges.

    The token can also be provided through the `CONSUL_TOKEN` or `CONSUL_HTTP_TOKEN` environment variables. | none | -| `auth` | Optional | [auth](/docs/nia/configuration#auth) | HTTP basic authentication for communicating with Consul || -| `tls` | Optional | [tls](/docs/nia/configuration#tls-1) | Secure client connection with Consul || -| `transport` | Optional | [transport](/docs/nia/configuration#transport) | Low-level network connection details || -| `service_registration` | Optional| [service_registration](/docs/nia/configuration#service-registration) | Options for how CTS will register itself as a service with a health check to Consul. || +| `token` | Optional | string | The ACL token to use for client communication with the local Consul agent. See [ACL Requirements](/consul/docs/nia/configuration#acl-requirements) for required privileges.

    The token can also be provided through the `CONSUL_TOKEN` or `CONSUL_HTTP_TOKEN` environment variables. | none | +| `auth` | Optional | [auth](/consul/docs/nia/configuration#auth) | HTTP basic authentication for communicating with Consul || +| `tls` | Optional | [tls](/consul/docs/nia/configuration#tls-1) | Secure client connection with Consul || +| `transport` | Optional | [transport](/consul/docs/nia/configuration#transport) | Low-level network connection details || +| `service_registration` | Optional| [service_registration](/consul/docs/nia/configuration#service-registration) | Options for how CTS will register itself as a service with a health check to Consul. || ### ACL requirements -The following table describes the ACL policies required by CTS. For more information, refer to the [Secure Consul-Terraform-Sync for Production](https://learn.hashicorp.com/tutorials/consul/consul-terraform-sync-secure?utm_source=docs#configure-acl-privileges-for-consul-terraform-sync) tutorial. +The following table describes the ACL policies required by CTS. For more information, refer to the [Secure Consul-Terraform-Sync for Production](/consul/tutorials/network-infrastructure-automation/consul-terraform-sync-secure?utm_source=docs#configure-acl-privileges-for-consul-terraform-sync) tutorial. | Policy | Resources | | ------ | --------- | @@ -136,8 +136,8 @@ The following table describes the ACL policies required by CTS. For more informa | `node:read` | Any nodes hosting services monitored by tasks | | `keys:read` | Any Consul KV pairs monitored by tasks | | `namespace:read` | Any namespaces for resources monitored by tasks | -| `service:write` | The CTS service when [service registration](/docs/nia/configuration#service-registration) is enabled | -| `keys:write` | `consul-terraform-sync/` Only required when using Consul as the [Terraform backend](/docs/nia/configuration#backend). | +| `service:write` | The CTS service when [service registration](/consul/docs/nia/configuration#service-registration) is enabled | +| `keys:write` | `consul-terraform-sync/` Only required when using Consul as the [Terraform backend](/consul/docs/nia/configuration#backend). | ### Auth @@ -151,7 +151,7 @@ Configures HTTP basic authentication for communicating with Consul. ### TLS -Configure TLS to use a secure client connection with Consul. Using HTTP/2 can solve issues related to hitting Consul's maximum connection limits, as well as improve efficiency when processing many blocking queries. This option is required for Consul-Terraform-Sync when connecting to a [Consul agent with TLS verification enabled for HTTPS connections](/docs/agent/config/config-files#verify_incoming). +Configure TLS to use a secure client connection with Consul. Using HTTP/2 can solve issues related to hitting Consul's maximum connection limits, as well as improve efficiency when processing many blocking queries. This option is required for Consul-Terraform-Sync when connecting to a [Consul agent with TLS verification enabled for HTTPS connections](/consul/docs/agent/config/config-files#verify_incoming). If Consul is using a self-signed certificate that you have not added to the global CA chain, you can set this certificate with `ca_cert` or `ca_path`. Alternatively, you can disable SSL verification by setting `verify` to false. However, disabling verification is a potential security vulnerability. @@ -168,7 +168,7 @@ If Consul is using a self-signed certificate that you have not added to the glob ### Transport Configures the low-level network connection details to Consul. -To achieve the shortest latency between a Consul service update to a task execution, configure `max_idle_conns_per_host` equal to or greater than the number of services in automation across all tasks. This value should be lower than the configured [`http_max_conns_per_client`](/docs/agent/config/config-files#http_max_conns_per_client) for the Consul agent. +To achieve the shortest latency between a Consul service update to a task execution, configure `max_idle_conns_per_host` equal to or greater than the number of services in automation across all tasks. This value should be lower than the configured [`http_max_conns_per_client`](/consul/docs/agent/config/config-files#http_max_conns_per_client) for the Consul agent. If `max_idle_conns_per_host` and the number of services in automation is greater than the Consul agent limit, CTS may error due to connection limits (status code 429). You may increase the agent limit with caution. _Note: requests to the Consul agent made by Terraform subprocesses or any other process on the same host as CTS will contribute to the Consul agent connection limit._ @@ -184,20 +184,20 @@ If `max_idle_conns_per_host` and the number of services in automation is greater ### Service registration -CTS automatically registers itself with Consul as a service with a health check, using the [`id`](/docs/nia/configuration#id) configuration as the service ID. CTS deregisters itself with Consul when CTS stops gracefully. If CTS is unable to register with Consul, then it will log the error and continue without exiting. +CTS automatically registers itself with Consul as a service with a health check, using the [`id`](/consul/docs/nia/configuration#id) configuration as the service ID. CTS deregisters itself with Consul when CTS stops gracefully. If CTS is unable to register with Consul, then it will log the error and continue without exiting. -Service registration requires that the [Consul token](/docs/nia/configuration#consul) has an ACL policy of `service:write` for the CTS service. +Service registration requires that the [Consul token](/consul/docs/nia/configuration#consul) has an ACL policy of `service:write` for the CTS service. | Parameter | Required | Type | Description | Default | | --------- | -------- | ---- | ----------- | ------- | -| `enabled` | Optional | boolean | Enables CTS to register itself as a service with Consul. When service registration is enabled for a [CTS instance configured for high availability](/docs/nia/usage/run-ha), the instance also registers itself with a new tag using the `cts-cluster:` format. | `true` | -| `service_name` | Optional | string | The service name for CTS. We recommended specifying the same name used for [`high_availability.cluster.name`](#high-availability-cluster) value if [CTS is configured for high availability](/docs/nia/usage/run-ha). | `consul-terraform-sync` | +| `enabled` | Optional | boolean | Enables CTS to register itself as a service with Consul. When service registration is enabled for a [CTS instance configured for high availability](/consul/docs/nia/usage/run-ha), the instance also registers itself with a new tag using the `cts-cluster:` format. | `true` | +| `service_name` | Optional | string | The service name for CTS. We recommended specifying the same name used for [`high_availability.cluster.name`](#high-availability-cluster) value if [CTS is configured for high availability](/consul/docs/nia/usage/run-ha). | `consul-terraform-sync` | | `address` | Optional | string | The IP address or hostname for CTS. | IP address of the Consul agent node | | `namespace` | Optional | string | The namespace to register CTS in. | In order of precedence:
    1. Inferred from the CTS ACL token
    2. The `default` namespace. | | `default_check.enabled` | Optional | boolean | Enables CTS to create the default health check. | `true` | -| `default_check.address` | Optional | string | The address to use for the default HTTP health check. Needs to include the scheme (`http`/`https`) and the port, if applicable. | `http://localhost:` or `https://localhost:`. Determined from the [port configuration](/docs/nia/configuration#port) and whether [TLS is enabled](/docs/nia/configuration#enabled-2) on the CTS API. | +| `default_check.address` | Optional | string | The address to use for the default HTTP health check. Needs to include the scheme (`http`/`https`) and the port, if applicable. | `http://localhost:` or `https://localhost:`. Determined from the [port configuration](/consul/docs/nia/configuration#port) and whether [TLS is enabled](/consul/docs/nia/configuration#enabled-2) on the CTS API. | -The default health check is an [HTTP check](/docs/discovery/checks#http-interval) that calls the [Health API](/docs/nia/api/health). The following table describes the values CTS sets for this default check, corresponding to the [Consul register check API](/api-docs/agent/check#register-check). If an option is not listed in this table, then CTS is using the default value. +The default health check is an [HTTP check](/consul/docs/discovery/checks#http-interval) that calls the [Health API](/consul/docs/nia/api/health). The following table describes the values CTS sets for this default check, corresponding to the [Consul register check API](/consul/api-docs/agent/check#register-check). If an option is not listed in this table, then CTS is using the default value. | Parameter | Value | | --------- | ----- | @@ -206,7 +206,7 @@ The default health check is an [HTTP check](/docs/discovery/checks#http-interval | Namespace | `service_registration.namespace` | | Notes | `Check created by Consul-Terraform-Sync`| | DeregisterCriticalServiceAfter | `30m` | -| ServiceID | [`id`](/docs/nia/configuration#id) | +| ServiceID | [`id`](/consul/docs/nia/configuration#id) | | Status | `critical` | | HTTP | `/v1/health` | | Method | `GET` | @@ -216,7 +216,7 @@ The default health check is an [HTTP check](/docs/discovery/checks#http-interval ## High availability -Add a `high_availability` block to your configuration to enable CTS to run in high availability mode. Refer to [Run Consul-Terraform-Sync with High Availability](/docs/nia/usage/run-ha) for additional information. The `high_availability` block contains the following configuration items. +Add a `high_availability` block to your configuration to enable CTS to run in high availability mode. Refer to [Run Consul-Terraform-Sync with High Availability](/consul/docs/nia/usage/run-ha) for additional information. The `high_availability` block contains the following configuration items. ### High availability cluster @@ -225,7 +225,7 @@ The `cluster` parameter contains configurations for the cluster you want to oper | Parameter | Description| Required | Type | | --------- | ---------- | -------- | ------| | `name` | Specifies the name of the cluster operating with high availability enabled. | Required | String | -| `storage` | Configures how CTS stores state information. Refer to [State storage and persistence](/docs/nia/architecture#state-storage-and-persistence) for additional information. You can define storage for the `"consul"` resource. Refer to [High availability cluster storage](#high-availability-cluster-storage) for additional information. | Optional | Object | +| `storage` | Configures how CTS stores state information. Refer to [State storage and persistence](/consul/docs/nia/architecture#state-storage-and-persistence) for additional information. You can define storage for the `"consul"` resource. Refer to [High availability cluster storage](#high-availability-cluster-storage) for additional information. | Optional | Object | #### High availability cluster storage @@ -245,7 +245,7 @@ The `instance` parameter is an object that contains configurations unique to the ## Service -~> **Note:** Deprecated in CTS 0.5.0 and will be removed in a future major release. `service` blocks are used to define the `task` block's `services` fields, which were also deprecated and replaced with [Services Condition](/docs/nia/configuration#services-condition) and [Services Module Input](/docs/nia/configuration#services-module-input). `service` block configuration can be replaced by configuring the equivalent fields of the corresponding Services Condition and Services Module Input. Refer to [0.5.0 release notes](/docs/release-notes/consul-terraform-sync/v0_5_x#deprecate-service-block) for examples. +~> **Note:** Deprecated in CTS 0.5.0 and will be removed in a future major release. `service` blocks are used to define the `task` block's `services` fields, which were also deprecated and replaced with [Services Condition](/consul/docs/nia/configuration#services-condition) and [Services Module Input](/consul/docs/nia/configuration#services-module-input). `service` block configuration can be replaced by configuring the equivalent fields of the corresponding Services Condition and Services Module Input. Refer to [0.5.0 release notes](/consul/docs/release-notes/consul-terraform-sync/v0_5_x#deprecate-service-block) for examples. A `service` block is an optional block to explicitly define the services configured in the `task` block's `services` field (deprecated). `service` blocks do not define services configured in the `task` block's `condition "services"` or `module_input "services` blocks. @@ -266,12 +266,12 @@ service { | `description` | Optional | string | Human-readable text to describe the service | none | | `datacenter` | Optional | string | Name of a datacenter to query for the task. | Datacenter of the agent that CTS queries. | | `namespace` | Optional | string |
    Namespace of the services to query for the task. | In order of precedence:
    1. Inferred from the CTS ACL token
    2. The `default` namespace. | -| `filter` | Optional | string | Expression used to additionally filter the services to monitor.

    Refer to the [services filtering documentation](/api-docs/health#filtering-2) and section about [how to write filter expressions](/api-docs/features/filtering#creating-expressions) for additional information. | none | -| `cts_user_defined_meta` | Optional | map[string] | User-defined metadata that is appended to the [service input variable](/docs/nia/terraform-modules#services-module-input) for compatible Terraform modules.

    Some modules do not use the configured metadata. Refer to the module configured for the task for information about metadata usage and expected keys and format.

    If multiple tasks depend on the same service but require different metadata, you can declare different sets of metadata for the same service. Define multiple service blocks for the service with unique IDs (and identical names) for those blocks. The metadata can then be separated per task based on the service IDs. | none| +| `filter` | Optional | string | Expression used to additionally filter the services to monitor.

    Refer to the [services filtering documentation](/consul/api-docs/health#filtering-2) and section about [how to write filter expressions](/consul/api-docs/features/filtering#creating-expressions) for additional information. | none | +| `cts_user_defined_meta` | Optional | map[string] | User-defined metadata that is appended to the [service input variable](/consul/docs/nia/terraform-modules#services-module-input) for compatible Terraform modules.

    Some modules do not use the configured metadata. Refer to the module configured for the task for information about metadata usage and expected keys and format.

    If multiple tasks depend on the same service but require different metadata, you can declare different sets of metadata for the same service. Define multiple service blocks for the service with unique IDs (and identical names) for those blocks. The metadata can then be separated per task based on the service IDs. | none| ## Task -A `task` block configures which task to execute in automation. Use the `condition` block to specify when the task executes. You can specify the `task` block multiple times to configure multiple tasks, or you can omit it entirely. If task blocks are not specified in your initial configuration, you can add them to a running CTS instance by using the [`/tasks` API endpoint](/docs/nia/api/tasks#tasks) or the [CLI's `task` command](/docs/nia/cli/task#task). +A `task` block configures which task to execute in automation. Use the `condition` block to specify when the task executes. You can specify the `task` block multiple times to configure multiple tasks, or you can omit it entirely. If task blocks are not specified in your initial configuration, you can add them to a running CTS instance by using the [`/tasks` API endpoint](/consul/docs/nia/api/tasks#tasks) or the [CLI's `task` command](/consul/docs/nia/cli/task#task). ```hcl task { @@ -292,14 +292,14 @@ task { - `name` - (string: required) Name is the unique name of the task (required). A task name must start with a letter or underscore and may contain only letters, digits, underscores, and dashes. - `enabled` - (bool: true) Enable or disable a task from running and managing resources. - `providers` - (list[string]) Providers is the list of provider names the task is dependent on. This is used to map [Terraform provider configuration](#terraform-provider) to the task. -- `services` - (list[string]) **Deprecated in CTS 0.5.0 and will be removed in a future major release. Use [Services Condition](/docs/nia/configuration#services-condition) or [Services Module Input](/docs/nia/configuration#services-module-input) instead. See [0.5.0 release notes](/docs/release-notes/consul-terraform-sync/v0_5_x#deprecate-services-field) for examples.** Specifies an optional list of logical service names or service IDs that the task monitors for changes in the Consul catalog. The `services` can act in different ways depending on the configuration of the task's `condition` block: +- `services` - (list[string]) **Deprecated in CTS 0.5.0 and will be removed in a future major release. Use [Services Condition](/consul/docs/nia/configuration#services-condition) or [Services Module Input](/consul/docs/nia/configuration#services-module-input) instead. See [0.5.0 release notes](/consul/docs/release-notes/consul-terraform-sync/v0_5_x#deprecate-services-field) for examples.** Specifies an optional list of logical service names or service IDs that the task monitors for changes in the Consul catalog. The `services` can act in different ways depending on the configuration of the task's `condition` block: - no `condition` block configured: `services` will act as the task's condition and provide the services information as module input - the `condition` block configured for type `services`: `services` is incompatible with this type of `condition` because both configure the services module input. CTS will return an error. - the `condition` block configured for all other types: `services` will act only to provide services module input. Service values that are not explicitly defined by a `service` block that have a matching ID are assumed to be logical service names in the `default` namespace. - `source` - (string: required) **Deprecated in CTS 0.5.0 and will be removed in a future major release. See the `module` field instead.** -- `module` - (string: required) Module is the location the driver uses to discover the Terraform module used for automation. The module's source can be local or remote on the [Terraform Registry](https://registry.terraform.io/) or private module registry. Read more on [Terraform module source and other supported types here](https://www.terraform.io/language/modules/sources). +- `module` - (string: required) Module is the location the driver uses to discover the Terraform module used for automation. The module's source can be local or remote on the [Terraform Registry](https://registry.terraform.io/) or private module registry. Read more on [Terraform module source and other supported types here](/terraform/language/modules/sources). - To use a private module with the [`terraform` driver](#terraform-driver), run the command [`terraform login [hostname]`](/terraform/tutorials/cloud/cloud-login?utm_source=docs) to authenticate the local Terraform CLI prior to starting CTS. - To use a private module with the [`terraform_cloud` driver](#terraform-cloud-driver), no extra steps are needed. @@ -315,7 +315,7 @@ task { module = "///" ``` -- `variable_files` - (list[string]) Specifies list of paths to [Terraform variable definition files (`.tfvars`)](https://www.terraform.io/language/values/variables#variable-definitions-tfvars-files). The content of these files should consist of only variable name assignments. The variable assignments must match the corresponding variable declarations made available by the Terraform module for the task. +- `variable_files` - (list[string]) Specifies list of paths to [Terraform variable definition files (`.tfvars`)](/terraform/language/values/variables#variable-definitions-tfvars-files). The content of these files should consist of only variable name assignments. The variable assignments must match the corresponding variable declarations made available by the Terraform module for the task. - Variables are loaded in the order they appear in the files. Duplicate variables are overwritten with the later value. _Unless specified by the module, configure arguments for Terraform providers using [`terraform_provider` blocks](#terraform-provider)._ @@ -360,7 +360,7 @@ When a `condition "services"` block is configured for a task, then the following These restrictions are due to the fact that the monitored services information for a task can only be set through one configuration option. Any services module input that the task needs should be configured solely through the `condition` block. -See [Task Execution: Services Condition](/docs/nia/tasks#services-condition) for more details on how tasks are triggered with a services condition. +See [Task Execution: Services Condition](/consul/docs/nia/tasks#services-condition) for more details on how tasks are triggered with a services condition. ```hcl task { @@ -405,17 +405,17 @@ task { | `names` | Required if `regexp` is not configured | list[string] | Names of Consul services to monitor. Only services that have their name listed in `names` are used by the task. | none | | `datacenter` | Optional | string | Name of a datacenter to query for the task. | Datacenter of the agent that CTS queries. | | `namespace` | Optional | string |
    Namespace of the services to query for the task. | In order of precedence:
    1. Inferred from the CTS ACL token
    2. The `default` namespace. | -| `filter` | Optional | string | Expression used to additionally filter the services to monitor.

    Refer to the [services filtering documentation](/api-docs/health#filtering-2) and section about [how to write filter expressions](/api-docs/features/filtering#creating-expressions) for additional information. | none | -| `cts_user_defined_meta` | Optional | map[string] | User-defined metadata that is appended to the [service input variable](/docs/nia/terraform-modules#services-module-input) for compatible Terraform modules.

    Some modules do not use the configured metadata. Refer to the module configured for the task for information about metadata usage and expected keys and format. | none| +| `filter` | Optional | string | Expression used to additionally filter the services to monitor.

    Refer to the [services filtering documentation](/consul/api-docs/health#filtering-2) and section about [how to write filter expressions](/consul/api-docs/features/filtering#creating-expressions) for additional information. | none | +| `cts_user_defined_meta` | Optional | map[string] | User-defined metadata that is appended to the [service input variable](/consul/docs/nia/terraform-modules#services-module-input) for compatible Terraform modules.

    Some modules do not use the configured metadata. Refer to the module configured for the task for information about metadata usage and expected keys and format. | none| | `source_includes_var` | Optional | boolean | **Deprecated in CTS 0.5.0 and will be removed in 0.8.0. See the `use_as_module_input` field instead.** | true | -| `use_as_module_input` | Optional | boolean | Whether or not the values of the condition object should also be used as input for the [`services` variable](/docs/nia/terraform-modules#services-variable) for the Terraform module

    Please refer to the selected module's documentation for guidance on how to configure this field. If configured inconsistently with the module, CTS will error and exit. | true | +| `use_as_module_input` | Optional | boolean | Whether or not the values of the condition object should also be used as input for the [`services` variable](/consul/docs/nia/terraform-modules#services-variable) for the Terraform module

    Please refer to the selected module's documentation for guidance on how to configure this field. If configured inconsistently with the module, CTS will error and exit. | true | #### Catalog-Services Condition A catalog-services condition block configures a task to only execute on service registration and deregistration, more specifically on first service instance registration and last service instance deregistration respectively. The catalog-services condition has additional configuration options to specify the services that can trigger the task on registration and deregistration. -See [Task Execution: Catalog Services Condition](/docs/nia/tasks#catalog-services-condition) for more information on how tasks are triggered with a catalog-services condition. +See [Task Execution: Catalog Services Condition](/consul/docs/nia/tasks#catalog-services-condition) for more information on how tasks are triggered with a catalog-services condition. ```hcl task { @@ -443,7 +443,7 @@ task { | `namespace` | Optional | string |
    Namespace of the services to query for the task. | In order of precedence:
    1. Inferred from the CTS ACL token
    2. The `default` namespace. | | `node_meta` | Optional | map[string] | Node metadata key/value pairs to use to filter services. Only services registered at a node with the specified key/value pairs are used by the task. | none | | `source_includes_var` | Optional | boolean | **Deprecated in CTS 0.5.0 and will be removed in 0.8.0. See the `use_as_module_input` field instead.** | true | -| `use_as_module_input` | Optional | boolean | Whether or not the values of the condition object should also be used as input for the [`catalog_services` variable](/docs/nia/terraform-modules#catalog-services-variable) for the Terraform module

    Please refer to the selected module's documentation for guidance on how to configure this field. If configured inconsistently with the module, CTS will error and exit. | true | +| `use_as_module_input` | Optional | boolean | Whether or not the values of the condition object should also be used as input for the [`catalog_services` variable](/consul/docs/nia/terraform-modules#catalog-services-variable) for the Terraform module

    Please refer to the selected module's documentation for guidance on how to configure this field. If configured inconsistently with the module, CTS will error and exit. | true | #### Consul KV Condition @@ -452,7 +452,7 @@ A `condition "consul-kv"` block configures a task to only execute on changes to When a `condition "consul-kv"` block is configured for a task, the task cannot be configured with a `module_input "consul-kv"` or `source_input "consul-kv"` (deprecated) block. The monitored consul-kv information for a task can only be set through one configuration option. Any consul-kv module input that the task needs should be configured solely through the `condition` block. -See [Task Execution: Consul KV Condition](/docs/nia/tasks#consul-kv-condition) for more information on how tasks are triggered with a consul-kv condition. +See [Task Execution: Consul KV Condition](/consul/docs/nia/tasks#consul-kv-condition) for more information on how tasks are triggered with a consul-kv condition. ```hcl task { @@ -478,7 +478,7 @@ task { | `datacenter` | Optional | string | Name of a datacenter to query for the task. | Datacenter of the agent that CTS queries. | | `namespace` | Optional | string |
    Namespace of the services to query for the task. | In order of precedence:
    1. Inferred from the CTS ACL token
    2. The `default` namespace. | | `source_includes_var` | Optional | boolean | **Deprecated in CTS 0.5.0 and will be removed in 0.8.0. See the `use_as_module_input` field instead.** | true | -| `use_as_module_input` | Optional | boolean | Whether or not the values of the condition object should also be used as input for the [`consul_kv` variable](/docs/nia/terraform-modules#consul-kv-variable) for the Terraform module

    Please refer to the selected module's documentation for guidance on how to configure this field. If configured inconsistently with the module, CTS will error and exit. | true | +| `use_as_module_input` | Optional | boolean | Whether or not the values of the condition object should also be used as input for the [`consul_kv` variable](/consul/docs/nia/terraform-modules#consul-kv-variable) for the Terraform module

    Please refer to the selected module's documentation for guidance on how to configure this field. If configured inconsistently with the module, CTS will error and exit. | true | #### Schedule Condition @@ -487,9 +487,9 @@ A scheduled task has a schedule condition block, which defines the schedule for Schedule tasks also rely on additional task configuration, separate from the condition block to determine the module input information to provide to the task module. See [`module_input`](#module_input) block configuration for details on how to configure module input. -See [Task Execution: Schedule Condition](/docs/nia/tasks#schedule-condition) for more information on how tasks are triggered with schedule conditions. +See [Task Execution: Schedule Condition](/consul/docs/nia/tasks#schedule-condition) for more information on how tasks are triggered with schedule conditions. -See [Terraform Module: Module Input](/docs/nia/terraform-modules#module-input) for more information on module input options for a scheduled task. +See [Terraform Module: Module Input](/consul/docs/nia/terraform-modules#module-input) for more information on module input options for a scheduled task. ```hcl task { @@ -535,13 +535,13 @@ task { } ``` -~> The type of the `module_input` block that can be configured depends on the `condition` block type and the `services` field (deprecated). See [Task Module Input Restrictions](/docs/nia/configuration#task-module-input-restrictions) for more details. +~> The type of the `module_input` block that can be configured depends on the `condition` block type and the `services` field (deprecated). See [Task Module Input Restrictions](/consul/docs/nia/configuration#task-module-input-restrictions) for more details. The following sections describe the module input types that CTS supports. #### Services Module Input ((#services-source-input)) -This `services` module input object defines services registered to Consul whose metadata will be used as [services module input to the Terraform Module](/docs/nia/terraform-modules/#services-module-input). The following parameters are supported: +This `services` module input object defines services registered to Consul whose metadata will be used as [services module input to the Terraform Module](/consul/docs/nia/terraform-modules/#services-module-input). The following parameters are supported: | Parameter | Required | Type | Description | Default | | --------- | -------- | ---- | ----------- | ------- | @@ -549,8 +549,8 @@ This `services` module input object defines services registered to Consul whose | `names` | Required if `regexp` is not configured | list[string] | Names of Consul services to monitor. Only services that have their name listed in `names` are used by the task. | none | | `datacenter` | Optional | string | Name of a datacenter to query for the task. | Datacenter of the agent that CTS queries. | | `namespace` | Optional | string |
    String value indicating the namespace of the services to query for the task. | In order of precedence:
    1. Inferred from the CTS ACL token
    2. The `default` namespace. | -| `filter` | Optional | string | Expression used to additionally filter the services to monitor.

    Refer to the [services filtering documentation](/api-docs/health#filtering-2) and section about [how to write filter expressions](/api-docs/features/filtering#creating-expressions) for additional information. | none | -| `cts_user_defined_meta` | Optional | map[string] | User-defined metadata that is appended to the [service input variable](/docs/nia/terraform-modules#services-module-input) for compatible Terraform modules.

    Some modules do not use the configured metadata. Refer to the module configured for the task for information about metadata usage and expected keys and format. | none| +| `filter` | Optional | string | Expression used to additionally filter the services to monitor.

    Refer to the [services filtering documentation](/consul/api-docs/health#filtering-2) and section about [how to write filter expressions](/consul/api-docs/features/filtering#creating-expressions) for additional information. | none | +| `cts_user_defined_meta` | Optional | map[string] | User-defined metadata that is appended to the [service input variable](/consul/docs/nia/terraform-modules#services-module-input) for compatible Terraform modules.

    Some modules do not use the configured metadata. Refer to the module configured for the task for information about metadata usage and expected keys and format. | none| In the following example, the scheduled task queries all Consul services with `web` as the suffix. The metadata of matching services are provided to the Terraform module. @@ -578,7 +578,7 @@ task { #### Consul KV Module Input ((#consul-kv-source-input)) -A Consul KV module input block defines changes to Consul KV that will be monitored. These changes will then be provided as [Consul KV module input to the Terraform Module](/docs/nia/terraform-modules/#consul-kv-module-input). The module input can be configured for a single Consul KV entry or for any Consul KV entries that are prefixed with a given path. The following parameters are supported: +A Consul KV module input block defines changes to Consul KV that will be monitored. These changes will then be provided as [Consul KV module input to the Terraform Module](/consul/docs/nia/terraform-modules/#consul-kv-module-input). The module input can be configured for a single Consul KV entry or for any Consul KV entries that are prefixed with a given path. The following parameters are supported: | Parameter | Required | Type | Description | Default | | --------- | -------- | ---- | ----------- | ------- | @@ -650,16 +650,16 @@ driver "terraform" { } ``` -- `backend` - (obj) The backend stores [Terraform state files](https://www.terraform.io/language/state) for each task. This option is similar to the [Terraform backend configuration](https://www.terraform.io/language/settings/backends/configuration). CTS supports Terraform backends used as a state store. - - Supported backend options: [azurerm](https://www.terraform.io/language/settings/backends/azurerm), [consul](https://www.terraform.io/language/settings/backends/consul), [cos](https://www.terraform.io/language/settings/backends/cos), [gcs](https://www.terraform.io/language/settings/backends/gcs), [kubernetes](https://www.terraform.io/language/settings/backends/kubernetes), [local](https://www.terraform.io/language/settings/backends/local), [manta](https://www.terraform.io/language/v1.2.x/settings/backends/manta), [pg](https://www.terraform.io/language/settings/backends/pg) (Terraform v0.14+), [s3](https://www.terraform.io/language/settings/backends/s3). Visit the Terraform documentation links for details on backend configuration options. - - If omitted, CTS will generate default values and use configurations from the [`consul` block](#consul) to configure [Consul as the backend](https://www.terraform.io/language/settings/backends/consul), which stores Terraform statefiles in the Consul KV. The [ACL token provided for Consul authentication](#consul) is used to read and write to the KV store and requires [Consul KV privileges](https://learn.hashicorp.com/tutorials/consul/consul-terraform-sync-secure?utm_source=docs#configure-acl-privileges-for-consul-terraform-sync). The Consul KV path is the base path to store state files for tasks. The full path of each state file will have the task identifier appended to the end of the path, e.g. `consul-terraform-sync/terraform-env:task-name`. +- `backend` - (obj) The backend stores [Terraform state files](/terraform/language/state) for each task. This option is similar to the [Terraform backend configuration](/terraform/language/settings/backends/configuration). CTS supports Terraform backends used as a state store. + - Supported backend options: [azurerm](/terraform/language/settings/backends/azurerm), [consul](/terraform/language/settings/backends/consul), [cos](/terraform/language/settings/backends/cos), [gcs](/terraform/language/settings/backends/gcs), [kubernetes](/terraform/language/settings/backends/kubernetes), [local](/terraform/language/settings/backends/local), [manta](/terraform/language/v1.2.x/settings/backends/manta), [pg](/terraform/language/settings/backends/pg) (Terraform v0.14+), [s3](/terraform/language/settings/backends/s3). Visit the Terraform documentation links for details on backend configuration options. + - If omitted, CTS will generate default values and use configurations from the [`consul` block](#consul) to configure [Consul as the backend](/terraform/language/settings/backends/consul), which stores Terraform statefiles in the Consul KV. The [ACL token provided for Consul authentication](#consul) is used to read and write to the KV store and requires [Consul KV privileges](/consul/tutorials/network-infrastructure-automation/consul-terraform-sync-secure?utm_source=docs#configure-acl-privileges-for-consul-terraform-sync). The Consul KV path is the base path to store state files for tasks. The full path of each state file will have the task identifier appended to the end of the path, e.g. `consul-terraform-sync/terraform-env:task-name`. - The remote enhanced backend is not supported with the Terraform driver to run operations in Terraform Cloud. Use the [Terraform Cloud driver](#terraform-cloud-driver) to integrate CTS with Terraform Cloud for remote workspaces and remote operations. - The `local` backend type is not supported with CTS instances configured for high availability. If high availability is configured and the Terraform backend type is `local`, CTS logs an error and exits. - `log` - (bool) Enable all Terraform output (stderr and stdout) to be included in the CTS log. This is useful for debugging and development purposes. It may be difficult to work with log aggregators that expect uniform log format. - `path` - (string) The file path to install Terraform or discover an existing Terraform binary. If omitted, Terraform will be installed in the same directory as the CTS daemon. To resolve an incompatible Terraform version or to change versions will require removing the existing binary or change to a different path. - `persist_log` - (bool) Enable trace logging for each Terraform client to disk per task. This is equivalent to setting `TF_LOG_PATH=/terraform.log`. Trace log level results in verbose logging and may be useful for debugging and development purposes. We do not recommend enabling this for production. There is no log rotation and may quickly result in large files. -- `required_providers` - (obj: required) Declare each Terraform provider used across all tasks. This can be configured the same as how you would configure [Terraform `terraform.required_providers`](https://www.terraform.io/language/providers/requirements#requiring-providers) field to specify the source and version for each provider. CTS will process these requirements when preparing each task that uses the provider. -- `version` - (string) The Terraform version to install and run in automation for task execution. If omitted, the driver will install the latest [compatible release of Terraform](/docs/nia/compatibility#terraform). To change versions, remove the existing binary or change the path to install the desired version. Verify that the desired Terraform version is compatible across all Terraform modules used for CTS automation. +- `required_providers` - (obj: required) Declare each Terraform provider used across all tasks. This can be configured the same as how you would configure [Terraform `terraform.required_providers`](/terraform/language/providers/requirements#requiring-providers) field to specify the source and version for each provider. CTS will process these requirements when preparing each task that uses the provider. +- `version` - (string) The Terraform version to install and run in automation for task execution. If omitted, the driver will install the latest [compatible release of Terraform](/consul/docs/nia/compatibility#terraform). To change versions, remove the existing binary or change the path to install the desired version. Verify that the desired Terraform version is compatible across all Terraform modules used for CTS automation. ## Terraform Cloud Driver @@ -673,7 +673,7 @@ driver "terraform" { The Terraform Cloud driver enables CTS Enterprise to integrate with **Terraform Cloud**, including both the [self-hosted distribution](https://www.hashicorp.com/products/terraform/editions/enterprise) and the [managed service](https://www.hashicorp.com/products/terraform/editions/cloud). With this driver, CTS automates Terraform runs and remote operations for workspaces. -An overview of features enabled with Terraform Cloud can be viewed within the [Network Drivers](/docs/nia/network-drivers) documentation. +An overview of features enabled with Terraform Cloud can be viewed within the [Network Drivers](/consul/docs/nia/network-drivers) documentation. Only one network driver can be configured per deployment of CTS. @@ -703,16 +703,16 @@ driver "terraform-cloud" { - `hostname` - (string) The Terraform Cloud hostname to connect to. Can be overridden with the `TFC_HOSTNAME` environment variable. - `organization` - (string) The Terraform Cloud organization that hosts the managed workspaces by CTS. Can be overridden with the `TFC_ORGANIZATION` environment variable. -- `token` - (string) Required [Team API token](https://www.terraform.io/cloud-docs/users-teams-organizations/api-tokens#team-api-tokens) used for authentication with Terraform Cloud and workspace management. Only workspace permissions are needed for CTS. The token can also be provided using the `TFC_TOKEN` environment variable. +- `token` - (string) Required [Team API token](/terraform/cloud-docs/users-teams-organizations/api-tokens#team-api-tokens) used for authentication with Terraform Cloud and workspace management. Only workspace permissions are needed for CTS. The token can also be provided using the `TFC_TOKEN` environment variable. - We recommend creating a dedicated team and team API token to isolate automation by CTS from other Terraform Cloud operations. - `workspace_prefix` - (string) **Deprecated in CTS 0.5.0**, use the [`workspaces.prefix`](#prefix) option instead. Specifies a prefix to prepend to the automatically-generated workspace names used for automation. This prefix will be used by all tasks that use this driver. By default, when no prefix is configured, the workspace name will be the task name. When a prefix is configured, the workspace name will be `-`, with the character '-' between the workspace prefix and task name. For example, if you configure the prefix as "cts", then a task with the name "task-firewall" will have the workspace name "cts-task-firewall". - `workspaces` - Configure CTS management of Terraform Cloud workspaces. - `prefix` - (string) Specifies a prefix to prepend to the workspace names used for CTS task automation. This prefix will be used by all tasks that use this driver. By default, when no prefix is configured, the workspace name will be the task name. When a prefix is configured, the workspace name will be ``. For example, if you configure the prefix as "cts_", then a task with the name "task_firewall" will have the workspace name "cts_task_firewall". - - `tags` - (list[string]) Tags for CTS to add to all automated workspaces when the workspace is first created or discovered. Tags are added to discovered workspaces only if the workspace meets [automation requirements](/docs/nia/network-drivers/terraform-cloud#remote-workspaces) and satisfies the allowlist and denylist tag options. This option will not affect existing tags. Tags that were manually removed during runtime will be re-tagged when CTS restarts. Compatible with Terraform Cloud and Terraform Enterprise v202108-1+ + - `tags` - (list[string]) Tags for CTS to add to all automated workspaces when the workspace is first created or discovered. Tags are added to discovered workspaces only if the workspace meets [automation requirements](/consul/docs/nia/network-drivers/terraform-cloud#remote-workspaces) and satisfies the allowlist and denylist tag options. This option will not affect existing tags. Tags that were manually removed during runtime will be re-tagged when CTS restarts. Compatible with Terraform Cloud and Terraform Enterprise v202108-1+ - `tags_allowlist` - (list[string]) Tag requirement to use as a provision check for CTS automation of workspaces. When configured, Terraform Cloud workspaces must have at least one tag from the allow list for CTS to automate the workspace and runs. Compatible with Terraform Cloud and Terraform Enterprise v202108-1+. - `tags_denylist` - (list[string]) Tag restriction to use as a provision check for CTS automation of workspaces. When configured, Terraform Cloud workspaces must not have any tag from the deny list for CTS to automate the workspace and runs. Denied tags have higher priority than tags set in the `tags_allowlist` option. Compatible with Terraform Cloud and Terraform Enterprise v202108-1+. -- `required_providers` - (obj: required) Declare each Terraform provider used across all tasks. This can be configured the same as how you would configure [Terraform `terraform.required_providers`](https://www.terraform.io/language/providers/requirements#requiring-providers) field to specify the source and version for each provider. CTS will process these requirements when preparing each task that uses the provider. -- `tls` - Configure TLS to allow HTTPS connections to [Terraform Enterprise](https://www.terraform.io/enterprise/install/interactive/installer#tls-key-amp-cert). +- `required_providers` - (obj: required) Declare each Terraform provider used across all tasks. This can be configured the same as how you would configure [Terraform `terraform.required_providers`](/terraform/language/providers/requirements#requiring-providers) field to specify the source and version for each provider. CTS will process these requirements when preparing each task that uses the provider. +- `tls` - Configure TLS to allow HTTPS connections to [Terraform Enterprise](/terraform/enterprise/install/interactive/installer#tls-key-amp-cert). - `enabled` - (bool) Enable TLS. Providing a value for any of the TLS options will enable this parameter implicitly. - `ca_cert` - (string) The path to a PEM-encoded certificate authority file used to verify the authenticity of the connection to Terraform Enterprise over TLS. - `ca_path` - (string) The path to a directory of PEM-encoded certificate authority files used to verify the authenticity of the connection to Terraform Enterprise over TLS. @@ -727,13 +727,13 @@ driver "terraform-cloud" { } ``` -CTS generates local artifacts to prepare configuration versions used for workspace runs. The location of the files created can be set with the [`working_dir`](/docs/nia/configuration#working_dir) option or configured per task. When a task is configured with a local module and is run with the Terraform Cloud driver, the local module is copied and uploaded as a part of the configuration version. +CTS generates local artifacts to prepare configuration versions used for workspace runs. The location of the files created can be set with the [`working_dir`](/consul/docs/nia/configuration#working_dir) option or configured per task. When a task is configured with a local module and is run with the Terraform Cloud driver, the local module is copied and uploaded as a part of the configuration version. The version of Terraform to use for each workspace can also be set within the [task](#task) configuration. ## Terraform Provider -A `terraform_provider` block configures the options to interface with network infrastructure. Define a block for each provider required by the set of Terraform modules across all tasks. This block resembles [provider blocks for Terraform configuration](https://www.terraform.io/language/providers/configuration). To find details on how to configure a provider, refer to the corresponding documentation for the Terraform provider. The main directory of publicly available providers are hosted on the [Terraform Registry](https://registry.terraform.io/browse/providers). +A `terraform_provider` block configures the options to interface with network infrastructure. Define a block for each provider required by the set of Terraform modules across all tasks. This block resembles [provider blocks for Terraform configuration](/terraform/language/providers/configuration). To find details on how to configure a provider, refer to the corresponding documentation for the Terraform provider. The main directory of publicly available providers are hosted on the [Terraform Registry](https://registry.terraform.io/browse/providers). The below configuration captures the general design of defining a provider using the [AWS Terraform provider](https://registry.terraform.io/providers/hashicorp/aws/latest/docs) as an example. @@ -761,7 +761,7 @@ task { } ``` -~> **Note**: Provider arguments configured in CTS configuration files are written in plain text to the generated [`terraform.tfvars`](/docs/nia/network-drivers#terraform-tfvars) file for each Terraform workspace that references the provider. To exclude arguments or dynamic values from rendering to local files in plain text, use [`task_env` in addition to using dynamic configuration](#securely-configure-terraform-providers). +~> **Note**: Provider arguments configured in CTS configuration files are written in plain text to the generated [`terraform.tfvars`](/consul/docs/nia/network-drivers#terraform-tfvars) file for each Terraform workspace that references the provider. To exclude arguments or dynamic values from rendering to local files in plain text, use [`task_env` in addition to using dynamic configuration](#securely-configure-terraform-providers). ### Securely Configure Terraform Providers @@ -823,7 +823,7 @@ terraform_provider "example" { #### Vault -`with secret` queries the [Vault KV secrets engine](https://www.vaultproject.io/api-docs/secret/kv). Vault is an optional source that require operators to configure the Vault client with a [`vault` block](#vault-configuration). Access the secret using template dot notation `Data.data.`. +`with secret` queries the [Vault KV secrets engine](/vault/api-docs/secret/kv). Vault is an optional source that require operators to configure the Vault client with a [`vault` block](#vault-configuration). Access the secret using template dot notation `Data.data.`. ```hcl vault { @@ -857,7 +857,7 @@ terraform_provider "example" { ### Multiple Provider Configurations -CTS supports the [Terraform feature to define multiple configurations](https://www.terraform.io/language/providers/configuration#alias-multiple-provider-configurations) for the same provider by utilizing the `alias` meta-argument. Define multiple provider blocks with the same provider name and set the `alias` to a unique value across a given provider. Select which provider configuration to use for a task by specifying the configuration with the provider name and alias (`.`) within the list of providers in the [`task.provider`](#task) parameter. A task can use multiple providers, but only one provider instance of a provider is allowed per task. +CTS supports the [Terraform feature to define multiple configurations](/terraform/language/providers/configuration#alias-multiple-provider-configurations) for the same provider by utilizing the `alias` meta-argument. Define multiple provider blocks with the same provider name and set the `alias` to a unique value across a given provider. Select which provider configuration to use for a task by specifying the configuration with the provider name and alias (`.`) within the list of providers in the [`task.provider`](#task) parameter. A task can use multiple providers, but only one provider instance of a provider is allowed per task. The example CTS configuration below defines two similar tasks executing the same module with different instances of the AWS provider. diff --git a/website/content/docs/nia/enterprise/index.mdx b/website/content/docs/nia/enterprise/index.mdx index 9c20fcb71d..69aefb641b 100644 --- a/website/content/docs/nia/enterprise/index.mdx +++ b/website/content/docs/nia/enterprise/index.mdx @@ -7,24 +7,24 @@ description: >- # Consul-Terraform-Sync Enterprise -Consul-Terraform-Sync (CTS) Enterprise is available with [Consul Enterprise](https://www.hashicorp.com/products/consul) and requires a Consul [license](/docs/nia/enterprise/license) to be applied. +Consul-Terraform-Sync (CTS) Enterprise is available with [Consul Enterprise](https://www.hashicorp.com/products/consul) and requires a Consul [license](/consul/docs/nia/enterprise/license) to be applied. -Enterprise features of CTS address organization complexities of collaboration, operations, scale, and governance. CTS Enterprise supports an official integration with [Terraform Cloud](https://cloud.hashicorp.com/products/terraform) and [Terraform Enterprise](https://www.terraform.io/enterprise), the self-hosted distribution, to extend insight into dynamic updates of your network infrastructure. +Enterprise features of CTS address organization complexities of collaboration, operations, scale, and governance. CTS Enterprise supports an official integration with [Terraform Cloud](https://cloud.hashicorp.com/products/terraform) and [Terraform Enterprise](/terraform/enterprise), the self-hosted distribution, to extend insight into dynamic updates of your network infrastructure. | Features | Open Source | Enterprise | |----------|-------------|------------| | Consul Namespace | Default namespace only | Filter task triggers by any namespace | | Automation Driver | Terraform OSS | Terraform OSS, Terraform Cloud, or Terraform Enterprise | -| Terraform Workspaces | Local | Local workspaces with the Terraform driver or [remote workspaces](https://www.terraform.io/cloud-docs/workspaces) with the Terraform Cloud driver | -| Terraform Backend Options | [azurerm](https://www.terraform.io/language/settings/backends/azurerm), [consul](https://www.terraform.io/language/settings/backends/consul), [cos](https://www.terraform.io/language/settings/backends/cos), [gcs](https://www.terraform.io/language/settings/backends/gcs), [kubernetes](https://www.terraform.io/language/settings/backends/kubernetes), [local](https://www.terraform.io/language/settings/backends/local), [manta](https://www.terraform.io/language/v1.2.x/settings/backends/manta), [pg](https://www.terraform.io/language/settings/backends/pg), and [s3](https://www.terraform.io/language/settings/backends/s3) with the Terraform driver | The supported backends for CTS with the Terraform driver or Terraform Cloud with the Terraform Cloud driver | +| Terraform Workspaces | Local | Local workspaces with the Terraform driver or [remote workspaces](/terraform/cloud-docs/workspaces) with the Terraform Cloud driver | +| Terraform Backend Options | [azurerm](/terraform/language/settings/backends/azurerm), [consul](/terraform/language/settings/backends/consul), [cos](/terraform/language/settings/backends/cos), [gcs](/terraform/language/settings/backends/gcs), [kubernetes](/terraform/language/settings/backends/kubernetes), [local](/terraform/language/settings/backends/local), [manta](/terraform/language/v1.2.x/settings/backends/manta), [pg](/terraform/language/settings/backends/pg), and [s3](/terraform/language/settings/backends/s3) with the Terraform driver | The supported backends for CTS with the Terraform driver or Terraform Cloud with the Terraform Cloud driver | | Terraform Version | One Terraform version for all tasks | Optional Terraform version per task when using the Terraform Cloud driver | | Terraform Run Output | CTS logs | CTS logs or Terraform output organized by Terraform Cloud remote workspaces | | Credentials and secrets | On disk as `.tfvars` files or in shell environment | Secured variables stored in remote workspace | -| Audit | | Terraform audit logs ([Terraform Cloud](https://www.terraform.io/cloud-docs/api-docs/audit-trails) or [Terraform Enterprise](https://www.terraform.io/enterprise/admin/infrastructure/logging)) | -| Collaboration | | Run [history](https://www.terraform.io/cloud-docs/run/manage), [triggers](https://www.terraform.io/cloud-docs/workspaces/settings/run-triggers), and [notifications](https://www.terraform.io/cloud-docs/workspaces/settings/notifications) supported on Terraform Cloud | -| Governance | | [Sentinel](https://www.terraform.io/cloud-docs/policy-enforcement) to enforce governance policies as code | +| Audit | | Terraform audit logs ([Terraform Cloud](/terraform/cloud-docs/api-docs/audit-trails) or [Terraform Enterprise](/terraform/enterprise/admin/infrastructure/logging)) | +| Collaboration | | Run [history](/terraform/cloud-docs/run/manage), [triggers](/terraform/cloud-docs/workspaces/settings/run-triggers), and [notifications](/terraform/cloud-docs/workspaces/settings/notifications) supported on Terraform Cloud | +| Governance | | [Sentinel](/terraform/cloud-docs/policy-enforcement) to enforce governance policies as code | -The [Terraform Cloud driver](/docs/nia/configuration#terraform-cloud-driver) enables CTS Enterprise to integrate with Terraform Cloud or Terraform Enterprise. The [Terraform Cloud driver](/docs/nia/network-drivers/terraform-cloud) page provides an overview of how the integration works within CTS. +The [Terraform Cloud driver](/consul/docs/nia/configuration#terraform-cloud-driver) enables CTS Enterprise to integrate with Terraform Cloud or Terraform Enterprise. The [Terraform Cloud driver](/consul/docs/nia/network-drivers/terraform-cloud) page provides an overview of how the integration works within CTS. ## Consul Admin Partition Support CTS subscribes to a Consul agent. Depending on the admin partition the Consul agent is a part of and the services within the admin partition, CTS will be able to subscribe to those services and support the automation workflow. As such, admin partitions are not relevant to the CTS workflow. We recommend deploying a single CTS instance that subscribes to services/KV within a single partition and using a different CTS instance (or instances) to subscribe to services/KV in another partition. diff --git a/website/content/docs/nia/enterprise/license.mdx b/website/content/docs/nia/enterprise/license.mdx index 2c7dececfc..fd71d01047 100644 --- a/website/content/docs/nia/enterprise/license.mdx +++ b/website/content/docs/nia/enterprise/license.mdx @@ -11,14 +11,14 @@ description: >- Licenses are only required for Consul-Terraform-Sync (CTS) Enterprise     -CTS Enterprise binaries require a [Consul Enterprise license](/docs/enterprise/license/overview) to run. There is no CTS Enterprise specific license. As a result, CTS Enterprise's licensing is very similar to Consul Enterprise. +CTS Enterprise binaries require a [Consul Enterprise license](/consul/docs/enterprise/license/overview) to run. There is no CTS Enterprise specific license. As a result, CTS Enterprise's licensing is very similar to Consul Enterprise. All CTS Enterprise features are available with a valid Consul Enterprise license, regardless of your Consul Enterprise packaging or pricing model. -To get a trial license for CTS, you can sign-up for the [trial license for Consul Enterprise](/docs/enterprise/license/faq#q-where-can-users-get-a-trial-license-for-consul-enterprise). +To get a trial license for CTS, you can sign-up for the [trial license for Consul Enterprise](/consul/docs/enterprise/license/faq#q-where-can-users-get-a-trial-license-for-consul-enterprise). ## Automatic License Retrieval -CTS automatically retrieves a license from Consul on startup and then attempts to retrieve a new license once a day. If the current license is reaching its expiration date, CTS attempts to retrieve a license with increased frequency, as defined by the [License Expiration Date Handling](/docs/nia/enterprise/license#license-expiration-handling). +CTS automatically retrieves a license from Consul on startup and then attempts to retrieve a new license once a day. If the current license is reaching its expiration date, CTS attempts to retrieve a license with increased frequency, as defined by the [License Expiration Date Handling](/consul/docs/nia/enterprise/license#license-expiration-handling). ~> Enabling automatic license retrieval is recommended when using HCP Consul, as HCP Consul licenses expire more frequently than Consul Enterprise licenses. Without auto-retrieval enabled, you have to restart CTS every time you load a new license. @@ -38,7 +38,7 @@ If a license needs to be manually set, choose one of the following methods (in o export CONSUL_LICENSE_PATH=// ``` -1. To point to the file containing the license, in the configuration file, configure the [`license`](/docs/nia/configuration#license) path option. +1. To point to the file containing the license, in the configuration file, configure the [`license`](/consul/docs/nia/configuration#license) path option. ```hcl license { @@ -46,14 +46,14 @@ If a license needs to be manually set, choose one of the following methods (in o } ``` -1. To point to the file containing the license, in the configuration file, configure the [`license_path`](/docs/nia/configuration#license_path) option i. **Deprecated in CTS 0.6.0 and will be removed in a future release. Use [license block](/docs/nia/configuration#license) instead.** +1. To point to the file containing the license, in the configuration file, configure the [`license_path`](/consul/docs/nia/configuration#license_path) option i. **Deprecated in CTS 0.6.0 and will be removed in a future release. Use [license block](/consul/docs/nia/configuration#license) instead.** ```hcl license_path = "//" ``` -~> **Note**: the [options to set the license and the order of precedence](/docs/enterprise/license/overview#binaries-without-built-in-licenses) are the same as Consul Enterprise server agents. -Visit the [Enterprise License Tutorial](https://learn.hashicorp.com/tutorials/nomad/hashicorp-enterprise-license?utm_source=docs) for detailed steps on how to install the license key. +~> **Note**: the [options to set the license and the order of precedence](/consul/docs/enterprise/license/overview#binaries-without-built-in-licenses) are the same as Consul Enterprise server agents. +Visit the [Enterprise License Tutorial](/nomad/tutorials/enterprise/hashicorp-enterprise-license?utm_source=docs) for detailed steps on how to install the license key. ### Updating the License Manually To update the license when it expires or is near the expiration date and automatic license retrieval is disabled: @@ -80,4 +80,4 @@ When approaching expiration and termination, by default, CTS Enterprise will att | At or after expiration (before termination) | License retrieval attempt every 1 minute | Error-level log every 1 minute | | At or after termination | Error-level log and exit | Error-level log and exit | -~> **Note**: Notification frequency and [grace period](/docs/enterprise/license/faq#q-is-there-a-grace-period-when-licenses-expire) behavior is the same as Consul Enterprise. +~> **Note**: Notification frequency and [grace period](/consul/docs/enterprise/license/faq#q-is-there-a-grace-period-when-licenses-expire) behavior is the same as Consul Enterprise. diff --git a/website/content/docs/nia/index.mdx b/website/content/docs/nia/index.mdx index 86443faad9..d24aaf2a52 100644 --- a/website/content/docs/nia/index.mdx +++ b/website/content/docs/nia/index.mdx @@ -11,7 +11,7 @@ Network Infrastructure Automation (NIA) enables dynamic updates to network infra CTS executes one or more automation tasks with the most recent service variable values from the Consul service catalog. Each task consists of a runbook automation written as a CTS compatible Terraform module using resources and data sources for the underlying network infrastructure. The `consul-terraform-sync` daemon runs on the same node as a Consul agent. -CTS is available as an open source and enterprise distribution. Follow the [Network Infrastructure Automation introduction tutorial](https://learn.hashicorp.com/tutorials/consul/consul-terraform-sync-intro?utm_source=docs) to get started with CTS OSS or read more about [CTS Enterprise](/docs/nia/enterprise). +CTS is available as an open source and enterprise distribution. Follow the [Network Infrastructure Automation introduction tutorial](/consul/tutorials/network-infrastructure-automation/consul-terraform-sync-intro?utm_source=docs) to get started with CTS OSS or read more about [CTS Enterprise](/consul/docs/nia/enterprise). ## Use Cases @@ -31,15 +31,15 @@ CTS is available as an open source and enterprise distribution. Follow the [Netw -> **Note:** The terminology "tasks" used throughout the documentation refers to all types of tasks except when specifically stated otherwise. -- `Network Drivers` - CTS uses [network drivers](/docs/nia/network-drivers) to execute and update network infrastructure. Drivers transform Consul service-level information into downstream changes by processing and abstracting API and resource details tied to specific network infrastructure. +- `Network Drivers` - CTS uses [network drivers](/consul/docs/nia/network-drivers) to execute and update network infrastructure. Drivers transform Consul service-level information into downstream changes by processing and abstracting API and resource details tied to specific network infrastructure. - `Network Infrastructure Automation (NIA)` - Enables dynamic updates to network infrastructure devices triggered when specific conditions, such as service changes and registration, are met. -- `Scheduled Tasks` - A scheduled task is a type of task that is triggered only on a schedule. It is configured with a [schedule condition](/docs/nia/configuration#schedule-condition). +- `Scheduled Tasks` - A scheduled task is a type of task that is triggered only on a schedule. It is configured with a [schedule condition](/consul/docs/nia/configuration#schedule-condition). - `Services` - A service in CTS represents a service that is registered with Consul for service discovery. Services are grouped by their service names. There may be more than one instance of a particular service, each with its own unique ID. CTS monitors services based on service names and can provide service instance details to a Terraform module for network automation. -- `Module Input` - A module input defines objects that provide values or metadata to the Terraform module. See [module input](/docs/nia/terraform-modules#module-input) for the supported metadata and values. For example, a user can configure a Consul KV module input to provide KV pairs as variables to their respective Terraform Module. +- `Module Input` - A module input defines objects that provide values or metadata to the Terraform module. See [module input](/consul/docs/nia/terraform-modules#module-input) for the supported metadata and values. For example, a user can configure a Consul KV module input to provide KV pairs as variables to their respective Terraform Module. The module input can be configured in a couple of ways: - Setting the `condition` block's `use_as_module_input` field to true @@ -53,15 +53,15 @@ CTS is available as an open source and enterprise distribution. Follow the [Netw - `Tasks` - A task is the translation of dynamic service information from the Consul Catalog into network infrastructure changes downstream. -- `Terraform Cloud` - Per the [Terraform documentation](https://www.terraform.io/cloud-docs), "Terraform Cloud" describes both Terraform Cloud and Terraform Enterprise, which are different distributions of the same application. Documentation will apply to both distributions unless specifically stated otherwise. +- `Terraform Cloud` - Per the [Terraform documentation](/terraform/cloud-docs), "Terraform Cloud" describes both Terraform Cloud and Terraform Enterprise, which are different distributions of the same application. Documentation will apply to both distributions unless specifically stated otherwise. -- `Terraform Module` - A [Terraform module](https://www.terraform.io/language/modules) is a container for multiple Terraform resources that are used together. +- `Terraform Module` - A [Terraform module](/terraform/language/modules) is a container for multiple Terraform resources that are used together. -- `Terraform Provider` - A [Terraform provider](https://www.terraform.io/language/providers) is responsible for understanding API interactions and exposing resources for an infrastructure type. +- `Terraform Provider` - A [Terraform provider](/terraform/language/providers) is responsible for understanding API interactions and exposing resources for an infrastructure type. ## Getting Started With Network Infrastructure Automation -The [Network Infrastructure Automation (NIA)](https://learn.hashicorp.com/collections/consul/network-infrastructure-automation?utm_source=docs) +The [Network Infrastructure Automation (NIA)](/consul/tutorials/network-infrastructure-automation?utm_source=docs) collection contains examples on how to configure CTS to perform Network Infrastructure Automation. The collection contains also a tutorial to secure your CTS configuration for a production @@ -73,4 +73,4 @@ module. - [Contribute](https://github.com/hashicorp/consul-terraform-sync) to the open source project - [Report](https://github.com/hashicorp/consul-terraform-sync/issues) bugs or request enhancements - [Discuss](https://discuss.hashicorp.com/tags/c/consul/29/consul-terraform-sync) with the community or ask questions -- [Build integrations](/docs/nia/terraform-modules) for CTS +- [Build integrations](/consul/docs/nia/terraform-modules) for CTS diff --git a/website/content/docs/nia/installation/configure.mdx b/website/content/docs/nia/installation/configure.mdx index bb6f170627..1f9d5265fc 100644 --- a/website/content/docs/nia/installation/configure.mdx +++ b/website/content/docs/nia/installation/configure.mdx @@ -7,13 +7,13 @@ description: >- # Configure Consul-Terraform-Sync -The page will cover the main components for configuring your Network Infrastructure Automation with Consul at a high level. For the full list of configuration options, visit the [Consul-Terraform-Sync (CTS) configuration page](/docs/nia/configuration). +The page will cover the main components for configuring your Network Infrastructure Automation with Consul at a high level. For the full list of configuration options, visit the [Consul-Terraform-Sync (CTS) configuration page](/consul/docs/nia/configuration). ## Tasks A task captures a network automation process by defining which network resources to update on a given condition. Configure CTS with one or more tasks that contain a list of Consul services, a Terraform module, and various Terraform providers. -Within the [`task` block](/docs/nia/configuration#task), the list of services for a task represents the service layer that drives network automation. The `module` is the discovery location of the Terraform module that defines the network automation process for the task. The `condition`, not shown below, defaults to the services condition when unconfigured such that network resources are updated on changes to the list of services over time. +Within the [`task` block](/consul/docs/nia/configuration#task), the list of services for a task represents the service layer that drives network automation. The `module` is the discovery location of the Terraform module that defines the network automation process for the task. The `condition`, not shown below, defaults to the services condition when unconfigured such that network resources are updated on changes to the list of services over time. Review the Terraform module to be used for network automation and identify the Terraform providers required by the module. If the module depends on a set of providers, include the list of provider names in the `providers` field to associate the corresponding provider configuration with the task. These providers will need to be configured later in a separate block. @@ -32,7 +32,7 @@ task { ## Terraform Providers -Configuring Terraform providers within CTS requires 2 config components. The first component is required within the [`driver.terraform` block](/docs/nia/configuration#terraform-driver). All providers configured for CTS must be listed within the `required_providers` stanza to satisfy a [Terraform v0.13+ requirement](https://www.terraform.io/language/providers/requirements#requiring-providers) for Terraform to discover and install them. The providers listed are later organized by CTS to be included in the appropriate Terraform configuration files for each task. +Configuring Terraform providers within CTS requires 2 config components. The first component is required within the [`driver.terraform` block](/consul/docs/nia/configuration#terraform-driver). All providers configured for CTS must be listed within the `required_providers` stanza to satisfy a [Terraform v0.13+ requirement](/terraform/language/providers/requirements#requiring-providers) for Terraform to discover and install them. The providers listed are later organized by CTS to be included in the appropriate Terraform configuration files for each task. ```hcl driver "terraform" { @@ -45,9 +45,9 @@ driver "terraform" { } ``` -The second component for configuring a provider is the [`terraform_provider` block](/docs/nia/configuration#terraform-provider). This block resembles [provider blocks for Terraform configuration](https://www.terraform.io/language/providers/configuration) and has the same responsibility for understanding API interactions and exposing resources for a specific infrastructure platform. +The second component for configuring a provider is the [`terraform_provider` block](/consul/docs/nia/configuration#terraform-provider). This block resembles [provider blocks for Terraform configuration](/terraform/language/providers/configuration) and has the same responsibility for understanding API interactions and exposing resources for a specific infrastructure platform. -Terraform modules configured for task automation may require configuring the referenced providers. For example, configuring the host address and authentication to interface with your network infrastructure. Refer to the Terraform provider documentation hosted on the [Terraform Registry](https://registry.terraform.io/browse/providers) to find available options. The `terraform_provider` block is loaded by CTS during runtime and processed to be included in [autogenerated Terraform configuration files](/docs/nia/network-drivers#provider) used for task automation. Omitting the `terraform_provider` block for a provider will defer to the Terraform behavior assuming an empty default configuration. +Terraform modules configured for task automation may require configuring the referenced providers. For example, configuring the host address and authentication to interface with your network infrastructure. Refer to the Terraform provider documentation hosted on the [Terraform Registry](https://registry.terraform.io/browse/providers) to find available options. The `terraform_provider` block is loaded by CTS during runtime and processed to be included in [autogenerated Terraform configuration files](/consul/docs/nia/network-drivers#provider) used for task automation. Omitting the `terraform_provider` block for a provider will defer to the Terraform behavior assuming an empty default configuration. ```hcl terraform_provider "myprovider" { diff --git a/website/content/docs/nia/installation/install.mdx b/website/content/docs/nia/installation/install.mdx index 1e50955d8f..a8027b4436 100644 --- a/website/content/docs/nia/installation/install.mdx +++ b/website/content/docs/nia/installation/install.mdx @@ -7,14 +7,14 @@ description: >- # Install Consul-Terraform-Sync -Refer to the [introduction](https://learn.hashicorp.com/tutorials/consul/consul-terraform-sync-intro?utm_source=docs) tutorial for details about installing, configuring, and running Consul-Terraform-Sync (CTS) on your local machine with the Terraform driver. +Refer to the [introduction](/consul/tutorials/network-infrastructure-automation/consul-terraform-sync-intro?utm_source=docs) tutorial for details about installing, configuring, and running Consul-Terraform-Sync (CTS) on your local machine with the Terraform driver. ## Install Consul-Terraform-Sync -To install CTS, find the [appropriate package](https://releases.hashicorp.com/consul-terraform-sync/) for your system and download it as a zip archive. For the CTS Enterprise binary, download a zip archive with the `+ent` metadata. [CTS Enterprise requires a Consul Enterprise license](/docs/nia/enterprise/license) to run. +To install CTS, find the [appropriate package](https://releases.hashicorp.com/consul-terraform-sync/) for your system and download it as a zip archive. For the CTS Enterprise binary, download a zip archive with the `+ent` metadata. [CTS Enterprise requires a Consul Enterprise license](/consul/docs/nia/enterprise/license) to run. Unzip the package to extract the binary named `consul-terraform-sync`. Move the `consul-terraform-sync` binary to a location available on your `PATH`. @@ -94,7 +94,7 @@ $ consul-terraform-sync -version ## Connect your Consul Cluster -CTS connects with your Consul cluster in order to monitor the Consul catalog for service changes. These service changes lead to downstream updates to your network devices. You can configure your Consul cluster in CTS with the [Consul block](/docs/nia/configuration#consul). Below is an example: +CTS connects with your Consul cluster in order to monitor the Consul catalog for service changes. These service changes lead to downstream updates to your network devices. You can configure your Consul cluster in CTS with the [Consul block](/consul/docs/nia/configuration#consul). Below is an example: ```hcl consul { @@ -107,7 +107,7 @@ consul { CTS interacts with your network device through a network driver. For the Terraform network driver, CTS uses Terraform providers to make changes to your network infrastructure resources. You can reference existing provider docs on the Terraform Registry to configure each provider or create a new Terraform provider. -Once you have identified a Terraform provider for all of your network devices, you can configure them in CTS with a [`terraform_provider` block](/docs/nia/configuration#terraform-provider) for each network device. Below is an example: +Once you have identified a Terraform provider for all of your network devices, you can configure them in CTS with a [`terraform_provider` block](/consul/docs/nia/configuration#terraform-provider) for each network device. Below is an example: ```hcl terraform_provider "fake-firewall" { @@ -121,4 +121,4 @@ This provider is then used by task(s) to execute a Terraform module that will up ### Multiple Instances per Provider -You might have multiple instances of the same type of network device; for example, multiple instances of a firewall or load balancer. You can configure each instance with its own provider block and distinguish it by the `alias` meta-argument. See [multiple provider configurations](/docs/nia/configuration#multiple-provider-configurations) for more details and an example of the configuration. +You might have multiple instances of the same type of network device; for example, multiple instances of a firewall or load balancer. You can configure each instance with its own provider block and distinguish it by the `alias` meta-argument. See [multiple provider configurations](/consul/docs/nia/configuration#multiple-provider-configurations) for more details and an example of the configuration. diff --git a/website/content/docs/nia/network-drivers/index.mdx b/website/content/docs/nia/network-drivers/index.mdx index bc845f4e0b..6bed69a779 100644 --- a/website/content/docs/nia/network-drivers/index.mdx +++ b/website/content/docs/nia/network-drivers/index.mdx @@ -15,19 +15,19 @@ The following table highlights some of the additional features Terraform and Ter | Network Driver | Description | Features | | -------------- | ----------- | -------- | -| [Terraform driver](/docs/nia/network-drivers/terraform) | CTS automates a local installation of the [Terraform CLI](https://www.terraform.io/) | - Local Terraform execution
    - Local workspace directories
    - [Backend options](/docs/nia/configuration#backend) available for state storage
    | -| [Terraform Cloud driver](/docs/nia/network-drivers/terraform-cloud) | CTS Enterprise automates remote workspaces on [Terraform Cloud](https://www.terraform.io/cloud-docs) | - [Remote Terraform execution](https://www.terraform.io/cloud-docs/run/remote-operations)
    - Concurrent runs
    - [Secured variables](https://www.terraform.io/cloud-docs/workspaces/variables)
    - [State versions](https://www.terraform.io/cloud-docs/workspaces/state)
    - [Sentinel](https://www.terraform.io/cloud-docs/policy-enforcement) to enforce governance policies as code
    - Audit [logs](https://www.terraform.io/enterprise/admin/infrastructure/logging) and [trails](https://www.terraform.io/cloud-docs/api-docs/audit-trails)
    - Run [history](https://www.terraform.io/cloud-docs/run/manage), [triggers](https://www.terraform.io/cloud-docs/workspaces/settings/run-triggers), and [notifications](https://www.terraform.io/cloud-docs/workspaces/settings/notifications)
    - [Terraform Cloud Agents](https://www.terraform.io/cloud-docs/agents) | +| [Terraform driver](/consul/docs/nia/network-drivers/terraform) | CTS automates a local installation of the [Terraform CLI](https://www.terraform.io/) | - Local Terraform execution
    - Local workspace directories
    - [Backend options](/consul/docs/nia/configuration#backend) available for state storage
    | +| [Terraform Cloud driver](/consul/docs/nia/network-drivers/terraform-cloud) | CTS Enterprise automates remote workspaces on [Terraform Cloud](/terraform/cloud-docs) | - [Remote Terraform execution](/terraform/cloud-docs/run/remote-operations)
    - Concurrent runs
    - [Secured variables](/terraform/cloud-docs/workspaces/variables)
    - [State versions](/terraform/cloud-docs/workspaces/state)
    - [Sentinel](/terraform/cloud-docs/policy-enforcement) to enforce governance policies as code
    - Audit [logs](/terraform/enterprise/admin/infrastructure/logging) and [trails](/terraform/cloud-docs/api-docs/audit-trails)
    - Run [history](/terraform/cloud-docs/run/manage), [triggers](/terraform/cloud-docs/workspaces/settings/run-triggers), and [notifications](/terraform/cloud-docs/workspaces/settings/notifications)
    - [Terraform Cloud Agents](/terraform/cloud-docs/agents) | ## Understanding Terraform Automation CTS automates Terraform execution using a templated configuration to carry out infrastructure changes. The auto-generated configuration leverages input variables sourced from Consul and builds on top of reusable Terraform modules published and maintained by HashiCorp partners and the community. CTS can also run your custom built modules that suit your team's specific network automation needs. -The network driver for CTS determines how the Terraform automation operates. Visit the driver pages to read more about the [Terraform driver](/docs/nia/network-drivers/terraform) and the [Terraform Cloud driver](/docs/nia/network-drivers/terraform-cloud). +The network driver for CTS determines how the Terraform automation operates. Visit the driver pages to read more about the [Terraform driver](/consul/docs/nia/network-drivers/terraform) and the [Terraform Cloud driver](/consul/docs/nia/network-drivers/terraform-cloud). ### Upgrading Terraform -Upgrading the Terraform version used by CTS may introduce breaking changes that can impact the Terraform modules. Refer to the Terraform [upgrade guides](https://www.terraform.io/language/upgrade-guides) for details before upgrading. +Upgrading the Terraform version used by CTS may introduce breaking changes that can impact the Terraform modules. Refer to the Terraform [upgrade guides](/terraform/language/upgrade-guides) for details before upgrading. The following versions were identified as containing changes that may impact Terraform modules. -- [Terraform v0.15](https://www.terraform.io/language/v1.1.x/upgrade-guides/0-15) +- [Terraform v0.15](/terraform/language/v1.1.x/upgrade-guides/0-15) diff --git a/website/content/docs/nia/network-drivers/terraform-cloud.mdx b/website/content/docs/nia/network-drivers/terraform-cloud.mdx index c0c7d08fde..2a9c384507 100644 --- a/website/content/docs/nia/network-drivers/terraform-cloud.mdx +++ b/website/content/docs/nia/network-drivers/terraform-cloud.mdx @@ -18,20 +18,20 @@ This page describes how the Terraform Cloud driver operates within CTS. ## Terraform Workspace Automation -CTS manages Terraform runs following the [API-driven run workflow](https://www.terraform.io/cloud-docs/run/api) for workspaces in Terraform Cloud. +CTS manages Terraform runs following the [API-driven run workflow](/terraform/cloud-docs/run/api) for workspaces in Terraform Cloud. On startup, CTS: 1. Creates or discovers Terraform Cloud workspaces corresponding to the configured tasks. 2. Prepares the local environment and generates Terraform configuration files that make up the root module for each task. 3. Packages the generated files and uploads them as a configuration version for the task's workspace on Terraform Cloud. -Once all workspaces are set up, CTS monitors the Consul catalog for service changes. When relevant changes are detected, the Terraform Cloud driver dynamically updates input variables for that task directly as [workspace variables](https://www.terraform.io/cloud-docs/workspaces/variables) using the Terraform Cloud API. The driver then queues a run on the workspace, with auto-apply enabled, to update your network infrastructure. +Once all workspaces are set up, CTS monitors the Consul catalog for service changes. When relevant changes are detected, the Terraform Cloud driver dynamically updates input variables for that task directly as [workspace variables](/terraform/cloud-docs/workspaces/variables) using the Terraform Cloud API. The driver then queues a run on the workspace, with auto-apply enabled, to update your network infrastructure. ~> **Note:** Although workspaces for tasks are executed in isolated environments, this does not guarantee the infrastructure changes from concurrent task executions are independent. Ensure that modules across all tasks are not modifying the same resource objects or have overlapping changes that may result in race conditions during automation. ## Remote Workspaces -CTS will discover or create a new workspaces based on your configured tasks. The task configuration [`name`](/docs/nia/configuration#name-1) and [`description`](/docs/nia/configuration#description) are used to set the workspace name and description. The task configuration [`terraform_cloud_workspace`](/docs/nia/configuration#terraform_cloud_workspace) is used to set options like Terraform version, execution mode, and agent pool if relevant. CTS will also use any globally set workspace configurations, specified in the driver configuration [`workspaces`](/docs/nia/configuration#workspaces). +CTS will discover or create a new workspaces based on your configured tasks. The task configuration [`name`](/consul/docs/nia/configuration#name-1) and [`description`](/consul/docs/nia/configuration#description) are used to set the workspace name and description. The task configuration [`terraform_cloud_workspace`](/consul/docs/nia/configuration#terraform_cloud_workspace) is used to set options like Terraform version, execution mode, and agent pool if relevant. CTS will also use any globally set workspace configurations, specified in the driver configuration [`workspaces`](/consul/docs/nia/configuration#workspaces). [![CTS Workspace Overview](/img/nia/cts-tfc-workspace.png)](/img/nia/cts-tfc-workspace.png) @@ -39,7 +39,7 @@ Workspace automation requirements for CTS are in place to avoid overriding other * Must be set to remote or agent execution mode * Cannot be connected to a VCS * Cannot have an existing configuration version uploaded by another application -* Must satisfy workspace [tag requirements](/docs/nia/configuration#tags_allowlist) and [tag restrictions](/docs/nia/configuration#tags_denylist) set by the CTS operator +* Must satisfy workspace [tag requirements](/consul/docs/nia/configuration#tags_allowlist) and [tag restrictions](/consul/docs/nia/configuration#tags_denylist) set by the CTS operator Workspaces created by CTS will be configured with the following settings: @@ -47,12 +47,12 @@ Workspaces created by CTS will be configured with the following settings: | ------- | ----- | | Workspace name | CTS task name | | Description | CTS task description | -| Execution mode | [`task.terraform_cloud_workspace.execution_mode`](/docs/nia/configuration#execution_mode) or remote by default | +| Execution mode | [`task.terraform_cloud_workspace.execution_mode`](/consul/docs/nia/configuration#execution_mode) or remote by default | | Apply method | Auto apply | -| Terraform Version | [`task.terraform_cloud_workspace.terraform_version`](/docs/nia/configuration#terraform_version-1), [`task.terraform_version`](/docs/nia/configuration#terraform_version) (deprecated), or the latest [Terraform version compatible with CTS](/docs/nia/compatibility#terraform) available for the organization. | -| Tags | `source:cts` and [additional tags](/docs/nia/configuration#tags) set by the CTS operator | +| Terraform Version | [`task.terraform_cloud_workspace.terraform_version`](/consul/docs/nia/configuration#terraform_version-1), [`task.terraform_version`](/consul/docs/nia/configuration#terraform_version) (deprecated), or the latest [Terraform version compatible with CTS](/consul/docs/nia/compatibility#terraform) available for the organization. | +| Tags | `source:cts` and [additional tags](/consul/docs/nia/configuration#tags) set by the CTS operator | -Other workspace settings can be pre-configured or updated, such as setting the workspace to [manual apply](#manual-apply) or adding a [run notification](https://www.terraform.io/cloud-docs/workspaces/settings/notifications) to send messages to a Slack channel when CTS updates your network infrastructure. +Other workspace settings can be pre-configured or updated, such as setting the workspace to [manual apply](#manual-apply) or adding a [run notification](/terraform/cloud-docs/workspaces/settings/notifications) to send messages to a Slack channel when CTS updates your network infrastructure. ### Manual Apply @@ -64,11 +64,11 @@ There are two approaches to setup manual apply for a workspace managed by CTS ba * For CTS created workspaces, update the apply method from auto to manual via the Terraform Cloud web application or API. * For pre-configured workspaces, create the workspace prior to CTS task automation via the Terraform Cloud web application or API. 1. Create a workspace with the same name as the desired task. - 1. Set the workspace to [API-driven run workflow](https://www.terraform.io/cloud-docs/run/api) and the execution mode to remote. + 1. Set the workspace to [API-driven run workflow](/terraform/cloud-docs/run/api) and the execution mode to remote. 1. Ensure that the apply method for the workspace is set to manual apply. 1. Configure the task for the workspace and run CTS. --> **Tip**: Setup [run notifications](https://www.terraform.io/cloud-docs/workspaces/settings/notifications#creating-a-notification-configuration) for workspaces with manual apply to not miss automated runs by CTS. Look into setting the [buffer period](/docs/nia/configuration#buffer_period-1) or a [schedule condition](/docs/nia/configuration#schedule-condition) to group changes together and reduce runs requiring approval. +-> **Tip**: Setup [run notifications](/terraform/cloud-docs/workspaces/settings/notifications#creating-a-notification-configuration) for workspaces with manual apply to not miss automated runs by CTS. Look into setting the [buffer period](/consul/docs/nia/configuration#buffer_period-1) or a [schedule condition](/consul/docs/nia/configuration#schedule-condition) to group changes together and reduce runs requiring approval. ## Configuration Version @@ -86,12 +86,12 @@ sync-tasks/ - `main.tf` - The main file contains the terraform block, provider blocks, and a module block calling the module configured for the task. - `terraform` block - The corresponding provider source and versions for the task from the configuration files are placed into this block for the root module. - `provider` blocks - The provider blocks generated in the root module resemble the `terraform_provider` blocks from the configuration for CTS. They have identical arguments present and are set from the intermediate variable created per provider. - - `module` block - The module block is where the task's module is called as a [child module](https://www.terraform.io/language/modules#calling-a-child-module). The child module contains the core logic for automation. Required and optional input variables are passed as arguments to the module. + - `module` block - The module block is where the task's module is called as a [child module](/terraform/language/modules#calling-a-child-module). The child module contains the core logic for automation. Required and optional input variables are passed as arguments to the module. - `variables.tf` - This file contains three types of variable declarations: - - `services` input variable (required) determines module compatibility with Consul-Terraform Sync (read more on [compatible Terraform modules](/docs/nia/terraform-modules) for more details). - - Any additional [optional input variables](/docs/nia/terraform-modules#optional-input-variables) provided by CTS that the module may use. + - `services` input variable (required) determines module compatibility with Consul-Terraform Sync (read more on [compatible Terraform modules](/consul/docs/nia/terraform-modules) for more details). + - Any additional [optional input variables](/consul/docs/nia/terraform-modules#optional-input-variables) provided by CTS that the module may use. - Various intermediate variables used to configure providers. Intermediate provider variables are interpolated from the provider blocks and arguments configured in the CTS configuration. -- `variables.module.tf` - This file is created if there are [variables configured for the task](/docs/nia/configuration#variable_files) and contains the interpolated variable declarations that match the variables from configuration. These are then used to proxy the configured variables to the module through explicit assignment in the module block. +- `variables.module.tf` - This file is created if there are [variables configured for the task](/consul/docs/nia/configuration#variable_files) and contains the interpolated variable declarations that match the variables from configuration. These are then used to proxy the configured variables to the module through explicit assignment in the module block. ## Variables @@ -115,24 +115,24 @@ This section captures requirements for setting up CTS to integrate with your [Te 1. Hostname of your Terraform Cloud, self-hosted distribution 1. Name of your organization -1. [Team API token](https://www.terraform.io/cloud-docs/users-teams-organizations/api-tokens) used for authentication with Terraform Cloud +1. [Team API token](/terraform/cloud-docs/users-teams-organizations/api-tokens) used for authentication with Terraform Cloud -Prior to running CTS with a Terraform Cloud driver, you will need an account and organization set up, as well as a dedicated token. We recommend using a team token that is restricted to [Manage Workspaces](https://www.terraform.io/cloud-docs/users-teams-organizations/teams#managing-workspace-access)-level permissions. Below are the steps for the recommended setup. +Prior to running CTS with a Terraform Cloud driver, you will need an account and organization set up, as well as a dedicated token. We recommend using a team token that is restricted to [Manage Workspaces](/terraform/cloud-docs/users-teams-organizations/teams#managing-workspace-access)-level permissions. Below are the steps for the recommended setup. -The first step is to create an account with your Terraform Cloud service. After creating an account, create a new [organization](https://www.terraform.io/cloud-docs/users-teams-organizations/organizations#creating-organizations) or select an existing organization. The address of your Terraform Cloud service will be used to configure the [`hostname`](/docs/nia/configuration#hostname), and the organization name will be used to configure the [`organization`](/docs/nia/configuration#organization) on the Terraform Cloud driver. +The first step is to create an account with your Terraform Cloud service. After creating an account, create a new [organization](/terraform/cloud-docs/users-teams-organizations/organizations#creating-organizations) or select an existing organization. The address of your Terraform Cloud service will be used to configure the [`hostname`](/consul/docs/nia/configuration#hostname), and the organization name will be used to configure the [`organization`](/consul/docs/nia/configuration#organization) on the Terraform Cloud driver. -Once you have an account and organization, the next step is to [create a team](https://www.terraform.io/cloud-docs/users-teams-organizations/teams). We recommend using a dedicated team and team token to run and authenticate CTS. Using a team token has the benefits of restricting organization permissions as well as associating CTS automated actions with the team rather than an individual. +Once you have an account and organization, the next step is to [create a team](/terraform/cloud-docs/users-teams-organizations/teams). We recommend using a dedicated team and team token to run and authenticate CTS. Using a team token has the benefits of restricting organization permissions as well as associating CTS automated actions with the team rather than an individual. After creating a dedicated team, update the team's permissions with "Manage Workspaces" organization access-level. CTS's main work revolves around creating and managing workspaces. Therefore restricting the dedicated team's permission to Manage Workspaces level is sufficient and reduces security risk. [![CTS Terraform Team Setup](/img/nia/cts-tfc-team-setup.png)](/img/nia/cts-tfc-team-setup.png) -After setting the team's permissions, the final setup step is to [generate the associated team token](https://www.terraform.io/cloud-docs/users-teams-organizations/api-tokens), which can be done on the same team management page. This token will be used by CTS for API authentication and will be used to configure the [`token`](/docs/nia/configuration#token) on the Terraform Cloud driver. +After setting the team's permissions, the final setup step is to [generate the associated team token](/terraform/cloud-docs/users-teams-organizations/api-tokens), which can be done on the same team management page. This token will be used by CTS for API authentication and will be used to configure the [`token`](/consul/docs/nia/configuration#token) on the Terraform Cloud driver. ### Recommendations -We recommend configuring workspaces managed by CTS with [run notifications](https://www.terraform.io/cloud-docs/workspaces/settings/notifications) through the Terraform web application. Run notifications notify external systems about the progress of runs and could help notify users of CTS events, particularly errored runs. +We recommend configuring workspaces managed by CTS with [run notifications](/terraform/cloud-docs/workspaces/settings/notifications) through the Terraform web application. Run notifications notify external systems about the progress of runs and could help notify users of CTS events, particularly errored runs. [![CTS Terraform Cloud Run Notifications](/img/nia/cts-tfc-run-notifications.png)](/img/nia/cts-tfc-run-notifications.png) -In order to configure a run notification, users can [manually create a notification configuration](https://www.terraform.io/cloud-docs/workspaces/settings/notifications#creating-a-notification-configuration) for workspaces automated by CTS. A workspace may already exist for a task if the workspace name is identical to the configured task's [`name`](/docs/nia/configuration#name-2). This may occur if CTS has already already run and created the workspace for the task. This may also occur if the workspace is manually created for the task prior to CTS running. +In order to configure a run notification, users can [manually create a notification configuration](/terraform/cloud-docs/workspaces/settings/notifications#creating-a-notification-configuration) for workspaces automated by CTS. A workspace may already exist for a task if the workspace name is identical to the configured task's [`name`](/consul/docs/nia/configuration#name-2). This may occur if CTS has already already run and created the workspace for the task. This may also occur if the workspace is manually created for the task prior to CTS running. diff --git a/website/content/docs/nia/network-drivers/terraform.mdx b/website/content/docs/nia/network-drivers/terraform.mdx index 566fb1a750..1796c1298f 100644 --- a/website/content/docs/nia/network-drivers/terraform.mdx +++ b/website/content/docs/nia/network-drivers/terraform.mdx @@ -7,22 +7,22 @@ description: >- # Terraform Driver -Consul-Terraform-Sync (CTS) extends the Consul ecosystem to include Terraform as an officially supported tooling project. With the Terraform driver, CTS installs the [Terraform CLI](https://www.terraform.io/downloads) locally and runs Terraform commands based on monitored Consul changes. This page details how the Terraform driver operates using local workspaces and templated files. +Consul-Terraform-Sync (CTS) extends the Consul ecosystem to include Terraform as an officially supported tooling project. With the Terraform driver, CTS installs the [Terraform CLI](/terraform/downloads) locally and runs Terraform commands based on monitored Consul changes. This page details how the Terraform driver operates using local workspaces and templated files. ## Terraform CLI Automation On startup, CTS: 1. Downloads and installs Terraform -2. Prepares local workspace directories. Terraform configuration and execution for each task is organized as separate [Terraform workspaces](https://www.terraform.io/language/state/workspaces). The state files for tasks are independent of each other. +2. Prepares local workspace directories. Terraform configuration and execution for each task is organized as separate [Terraform workspaces](/terraform/language/state/workspaces). The state files for tasks are independent of each other. 3. Generates Terraform configuration files that make up the root module for each task. -Once all workspaces are set up, CTS monitors the Consul catalog for service changes. When relevant changes are detected, the Terraform driver dynamically updates input variables for that task using a template to render them to a file named [`terraform.tfvars`](/docs/nia/network-drivers#terraform-tfvars). This file is passed as a parameter to the Terraform CLI when executing `terraform plan` and `terraform apply` to update your network infrastructure with the latest Consul service details. +Once all workspaces are set up, CTS monitors the Consul catalog for service changes. When relevant changes are detected, the Terraform driver dynamically updates input variables for that task using a template to render them to a file named [`terraform.tfvars`](/consul/docs/nia/network-drivers#terraform-tfvars). This file is passed as a parameter to the Terraform CLI when executing `terraform plan` and `terraform apply` to update your network infrastructure with the latest Consul service details. ### Local Workspaces Within the CTS configuration for a task, practitioners can select the desired module to run for the task as well as set the condition to execute the task. Each task executed by the Terraform driver corresponds to an automated root module that calls the selected module in an isolated Terraform environment. CTS will manage concurrent execution of these tasks. -Autogenerated root modules for tasks are maintained in local subdirectories of the CTS working directory. Each subdirectory represents the local workspace for a task. By default, the working directory `sync-tasks` is created in the current directory. To configure where Terraform configuration files are stored, set [`working_dir`](/docs/nia/configuration#working_dir) to the desired path or configure the [`task.working_dir`](/docs/nia/configuration#working_dir-1) individually. +Autogenerated root modules for tasks are maintained in local subdirectories of the CTS working directory. Each subdirectory represents the local workspace for a task. By default, the working directory `sync-tasks` is created in the current directory. To configure where Terraform configuration files are stored, set [`working_dir`](/consul/docs/nia/configuration#working_dir) to the desired path or configure the [`task.working_dir`](/consul/docs/nia/configuration#working_dir-1) individually. ~> **Note:** Although Terraform state files for task workspaces are independent, this does not guarantee the infrastructure changes from concurrent task executions are independent. Ensure that modules across all tasks are not modifying the same resource objects or have overlapping changes that may result in race conditions during automation. @@ -48,13 +48,13 @@ The following files of the root module are generated for each task. An [example - `main.tf` - The main file contains the terraform block, provider blocks, and a module block calling the module configured for the task. - `terraform` block - The corresponding provider source and versions for the task from the configuration files are placed into this block for the root module. The Terraform backend from the configuration is also templated here. - `provider` blocks - The provider blocks generated in the root module resemble the `terraform_provider` blocks from the configuration for CTS. They have identical arguments present and are set from the intermediate variable created per provider. - - `module` block - The module block is where the task's module is called as a [child module](https://www.terraform.io/language/modules). The child module contains the core logic for automation. Required and optional input variables are passed as arguments to the module. + - `module` block - The module block is where the task's module is called as a [child module](/terraform/language/modules). The child module contains the core logic for automation. Required and optional input variables are passed as arguments to the module. - `variables.tf` - This file contains three types of variable declarations. - - `services` input variable (required) determines module compatibility with Consul-Terraform Sync (read more on [compatible Terraform modules](/docs/nia/terraform-modules) for more details). - - Any additional [optional input variables](/docs/nia/terraform-modules#optional-input-variables) provided by CTS that the module may use. + - `services` input variable (required) determines module compatibility with Consul-Terraform Sync (read more on [compatible Terraform modules](/consul/docs/nia/terraform-modules) for more details). + - Any additional [optional input variables](/consul/docs/nia/terraform-modules#optional-input-variables) provided by CTS that the module may use. - Various intermediate variables used to configure providers. Intermediate provider variables are interpolated from the provider blocks and arguments configured in the CTS configuration. -- `variables.module.tf` - This file is created if there are [variables configured for the task](/docs/nia/configuration#variable_files) and contains the interpolated variable declarations that match the variables from configuration. These are then used to proxy the configured variables to the module through explicit assignment in the module block. -- `providers.tfvars` - This file is created if there are [providers configured for the task](/docs/nia/configuration#providers) and defined [`terraform_provider` blocks](/docs/nia/configuration#terraform-provider). This file may contain sensitive information. To omit sensitive information from this file, you can [securely configure Terraform providers for CTS](/docs/nia/configuration#securely-configure-terraform-providers) using environment variables or templating. +- `variables.module.tf` - This file is created if there are [variables configured for the task](/consul/docs/nia/configuration#variable_files) and contains the interpolated variable declarations that match the variables from configuration. These are then used to proxy the configured variables to the module through explicit assignment in the module block. +- `providers.tfvars` - This file is created if there are [providers configured for the task](/consul/docs/nia/configuration#providers) and defined [`terraform_provider` blocks](/consul/docs/nia/configuration#terraform-provider). This file may contain sensitive information. To omit sensitive information from this file, you can [securely configure Terraform providers for CTS](/consul/docs/nia/configuration#securely-configure-terraform-providers) using environment variables or templating. - `terraform.tfvars` - The variable definitions file is where the services input variable and any optional CTS input variables are assigned values from Consul. It is periodically updated, typically when the task condition is met, to reflect the current state of Consul. - `terraform.tfvars.tmpl` - The template file is used by CTS to template information from Consul by using the HashiCorp configuration and templating library ([hashicorp/hcat](https://github.com/hashicorp/hcat)). diff --git a/website/content/docs/nia/tasks.mdx b/website/content/docs/nia/tasks.mdx index 2fc83adfa0..f3a0ab11f3 100644 --- a/website/content/docs/nia/tasks.mdx +++ b/website/content/docs/nia/tasks.mdx @@ -24,15 +24,15 @@ task { } ``` -In the example task above, the "fake-firewall" and "null" providers, listed in the `providers` field, are used. These providers themselves should be configured in their own separate [`terraform_provider` blocks](/docs/nia/configuration#terraform-provider). These providers are used in the Terraform module "example/firewall-policy/module", configured in the `module` field, to create, update, and destroy resources. This module may do something like use the providers to create and destroy firewall policy objects based on IP addresses. The IP addresses come from the "web" and "image" service instances configured in the `condition "services"` block. This service-level information is retrieved by CTS which watches Consul catalog for changes. +In the example task above, the "fake-firewall" and "null" providers, listed in the `providers` field, are used. These providers themselves should be configured in their own separate [`terraform_provider` blocks](/consul/docs/nia/configuration#terraform-provider). These providers are used in the Terraform module "example/firewall-policy/module", configured in the `module` field, to create, update, and destroy resources. This module may do something like use the providers to create and destroy firewall policy objects based on IP addresses. The IP addresses come from the "web" and "image" service instances configured in the `condition "services"` block. This service-level information is retrieved by CTS which watches Consul catalog for changes. -See [task configuration](/docs/nia/configuration#task) for more details on how to configure a task. +See [task configuration](/consul/docs/nia/configuration#task) for more details on how to configure a task. -A task can be either enabled or disabled using the [task cli](/docs/nia/cli/task). When enabled, tasks are executed and automated as described in sections below. However, disabled tasks do not execute when changes are detected from Consul catalog. Since disabled tasks do not execute, they also do not store [events](/docs/nia/tasks#event) until re-enabled. +A task can be either enabled or disabled using the [task cli](/consul/docs/nia/cli/task). When enabled, tasks are executed and automated as described in sections below. However, disabled tasks do not execute when changes are detected from Consul catalog. Since disabled tasks do not execute, they also do not store [events](/consul/docs/nia/tasks#event) until re-enabled. ## Task Execution -An enabled task can be configured to monitor and execute on different types of conditions, such as changes to services ([services condition](/docs/nia/tasks#services-condition)) or service registration and deregistration ([catalog-services condition](/docs/nia/tasks#catalog-services-condition)). +An enabled task can be configured to monitor and execute on different types of conditions, such as changes to services ([services condition](/consul/docs/nia/tasks#services-condition)) or service registration and deregistration ([catalog-services condition](/consul/docs/nia/tasks#catalog-services-condition)). A task can also monitor, but not execute on, other variables that provide additional information to the task's module. For example, a task with a catalog-services condition may execute on registration changes and additionally monitor service instances for IP information. @@ -43,10 +43,10 @@ All configured monitored information, regardless if it's used for execution or n Tasks with the services condition monitor and execute on either changes to a list of configured services or changes to any services that match a given regex. There are two ways to configure a task with a services condition. Only one of the two options below can be configured for a single task: -1. Configure a task's [`services`](/docs/nia/configuration#services) field (deprecated) to specify the list of services to trigger the task -1. Configure a task's `condition` block with the [services condition](/docs/nia/configuration#services-condition) type to specify services to trigger the task. +1. Configure a task's [`services`](/consul/docs/nia/configuration#services) field (deprecated) to specify the list of services to trigger the task +1. Configure a task's `condition` block with the [services condition](/consul/docs/nia/configuration#services-condition) type to specify services to trigger the task. -The services condition operates by monitoring the [Health List Nodes For Service API](/api-docs/health#list-nodes-for-service) and executing the task on any change of information for services configured. These changes include one or more changes to service values, like IP address, added or removed service instance, or tags. A complete list of values that would cause a task to run are expanded below: +The services condition operates by monitoring the [Health List Nodes For Service API](/consul/api-docs/health#list-nodes-for-service) and executing the task on any change of information for services configured. These changes include one or more changes to service values, like IP address, added or removed service instance, or tags. A complete list of values that would cause a task to run are expanded below: | Attribute | Description | | ----------------------- | ------------------------------------------------------------------------------------------------- | @@ -81,7 +81,7 @@ task { } ``` -The services condition can provide input for the [`services` input variable](/docs/nia/terraform-modules#services-variable) that is required for each CTS module. This can be provided depending on how the services condition is configured: +The services condition can provide input for the [`services` input variable](/consul/docs/nia/terraform-modules#services-variable) that is required for each CTS module. This can be provided depending on how the services condition is configured: - task's `services` field (deprecated): services object is automatically passed as module input - task's `condition "services"` block: users can configure the `use_as_module_input` field to optionally use the condition's services object as module input - Field was previously named `source_includes_var` (deprecated) @@ -90,7 +90,7 @@ The services condition can provide input for the [`services` input variable](/do Tasks with a catalog-services condition monitor and execute on service registration changes for services that satisfy the condition configuration. 'Service registration changes' specifically refers to service registration and deregistration where service registration occurs on the first service instance registration, and service deregistration occurs on the last service instance registration. Tasks with a catalog-services condition may, depending on the module, additionally monitor but not execute on service instance information. -The catalog-services condition operates by monitoring the [Catalog List Services API](/api-docs/catalog#list-services) and executing the task when services are added or removed in the list of registered services. Note, the task does not execute on changes to the tags of the list of services. This is similar to how changes to service instance information, mentioned above, also does not execute a task. +The catalog-services condition operates by monitoring the [Catalog List Services API](/consul/api-docs/catalog#list-services) and executing the task when services are added or removed in the list of registered services. Note, the task does not execute on changes to the tags of the list of services. This is similar to how changes to service instance information, mentioned above, also does not execute a task. Below is an example configuration for a task that will execute when a service with a name that matches the "web.*" regular expression in datacenter "dc1" has a registration change. It additionally monitors but does not execute on service instance changes to "web-api" in datacenter "dc2". @@ -113,13 +113,13 @@ task { } ``` -Using the condition block's `use_as_module_input` field, users can configure CTS to use the condition's object as module input for the [`catalog_services` input variable](/docs/nia/terraform-modules#catalog-services-variable). Users can refer to the configured module's documentation on how to set `use_as_module_input`. +Using the condition block's `use_as_module_input` field, users can configure CTS to use the condition's object as module input for the [`catalog_services` input variable](/consul/docs/nia/terraform-modules#catalog-services-variable). Users can refer to the configured module's documentation on how to set `use_as_module_input`. -See the [Catalog-Services Condition](/docs/nia/configuration#catalog-services-condition) configuration section for further details and additional configuration options. +See the [Catalog-Services Condition](/consul/docs/nia/configuration#catalog-services-condition) configuration section for further details and additional configuration options. ### Consul KV Condition -Tasks with a consul-kv condition monitor and execute on Consul KV changes for KV pairs that satisfy the condition configuration. The consul-kv condition operates by monitoring the [Consul KV API](/api-docs/kv#read-key) and executing the task when a configured KV entry is created, deleted, or updated. +Tasks with a consul-kv condition monitor and execute on Consul KV changes for KV pairs that satisfy the condition configuration. The consul-kv condition operates by monitoring the [Consul KV API](/consul/api-docs/kv#read-key) and executing the task when a configured KV entry is created, deleted, or updated. Based on the `recurse` option, the condition either monitors a single Consul KV pair for a given path or monitors all pairs that are prefixed by that path. In the example below, because `recurse` is set to true, the `path` option is treated as a prefix. Changes to an entry with the key `my-key` and an entry with the key `my-key/another-key` would both trigger the task. If `recurse` were set to false, then only changes to `my-key` would trigger the task. @@ -140,15 +140,15 @@ task { } ``` -Using the condition block's `use_as_module_input` field, users can configure CTS to use the condition's object as module input for the [`consul_kv` input variable](/docs/nia/terraform-modules#consul-kv-variable). Users can refer to the configured module's documentation on how to set `use_as_module_input`. +Using the condition block's `use_as_module_input` field, users can configure CTS to use the condition's object as module input for the [`consul_kv` input variable](/consul/docs/nia/terraform-modules#consul-kv-variable). Users can refer to the configured module's documentation on how to set `use_as_module_input`. -See the [Consul-KV Condition](/docs/nia/configuration#consul-kv-condition) configuration section for more details and additional configuration options. +See the [Consul-KV Condition](/consul/docs/nia/configuration#consul-kv-condition) configuration section for more details and additional configuration options. ### Schedule Condition -All scheduled tasks must be configured with a schedule condition. The schedule condition sets the cadence to trigger a task with a [`cron`](/docs/nia/configuration#cron) configuration. The schedule condition block does not support parameters to configure module input. As a result, inputs must be configured separately. You can configure [`module_input` blocks](/docs/nia/configuration#module_input) to define the module inputs. +All scheduled tasks must be configured with a schedule condition. The schedule condition sets the cadence to trigger a task with a [`cron`](/consul/docs/nia/configuration#cron) configuration. The schedule condition block does not support parameters to configure module input. As a result, inputs must be configured separately. You can configure [`module_input` blocks](/consul/docs/nia/configuration#module_input) to define the module inputs. -Below is an example configuration for a task that will execute every Monday, which is set by the schedule condition's [`cron`](/docs/nia/configuration#cron) configuration. The module input is defined by the `module_input` block. When the task is triggered on Monday, it will retrieve the latest information on "web" and "db" from Consul and provide this to the module's input variables. +Below is an example configuration for a task that will execute every Monday, which is set by the schedule condition's [`cron`](/consul/docs/nia/configuration#cron) configuration. The module input is defined by the `module_input` block. When the task is triggered on Monday, it will retrieve the latest information on "web" and "db" from Consul and provide this to the module's input variables. ```hcl task { @@ -167,25 +167,25 @@ task { Below are the available options for module input types and how to configure them: -- [Services module input](/docs/nia/terraform-modules/#services-module-input): - - [`task.services`](/docs/nia/configuration#services) field (deprecated) - - [`module_input "services"`](/docs/nia/configuration#services-configure-input) block +- [Services module input](/consul/docs/nia/terraform-modules/#services-module-input): + - [`task.services`](/consul/docs/nia/configuration#services) field (deprecated) + - [`module_input "services"`](/consul/docs/nia/configuration#services-configure-input) block - Block was previously named `source_input "services"` (deprecated) -- [Consul KV module input](/docs/nia/terraform-modules/#consul-kv-module-input): - - [`module_input "consul-kv"`](/docs/nia/configuration#consul-kv-module-input) +- [Consul KV module input](/consul/docs/nia/terraform-modules/#consul-kv-module-input): + - [`module_input "consul-kv"`](/consul/docs/nia/configuration#consul-kv-module-input) - Block was previously named `source_input "consul-kv"` (deprecated) #### Running Behavior Scheduled tasks generally run on schedule, but they can be triggered on demand when running CTS in the following ways: -- [Long-running mode](/docs/nia/cli#long-running-mode): At the beginning of the long-running mode, CTS first passes through a once-mode phase in which all tasks are executed once. Scheduled tasks will trigger once during this once-mode phase. This behavior also applies to tasks that are not scheduled. After once-mode has completed, scheduled tasks subsequently trigger on schedule. +- [Long-running mode](/consul/docs/nia/cli#long-running-mode): At the beginning of the long-running mode, CTS first passes through a once-mode phase in which all tasks are executed once. Scheduled tasks will trigger once during this once-mode phase. This behavior also applies to tasks that are not scheduled. After once-mode has completed, scheduled tasks subsequently trigger on schedule. -- [Inspect mode](/docs/nia/cli#inspect-mode): When running in inspect mode, the terminal will output a plan of proposed updates that would be made if the tasks were to trigger at that moment and then exit. No changes are applied in this mode. The outputted plan for a scheduled task is also the proposed updates that would be made if the task was triggered at that moment, even if off-schedule. +- [Inspect mode](/consul/docs/nia/cli#inspect-mode): When running in inspect mode, the terminal will output a plan of proposed updates that would be made if the tasks were to trigger at that moment and then exit. No changes are applied in this mode. The outputted plan for a scheduled task is also the proposed updates that would be made if the task was triggered at that moment, even if off-schedule. -- [Once mode](/docs/nia/cli#once-mode): During the once mode, all tasks are only triggered one time. Scheduled tasks will execute during once mode even if not on the schedule. +- [Once mode](/consul/docs/nia/cli#once-mode): During the once mode, all tasks are only triggered one time. Scheduled tasks will execute during once mode even if not on the schedule. -- [Enable CLI](/docs/nia/cli/task#task-enable): When a task is enabled through the CLI, any type of task, including scheduled tasks, will be triggered at that time. +- [Enable CLI](/consul/docs/nia/cli/task#task-enable): When a task is enabled through the CLI, any type of task, including scheduled tasks, will be triggered at that time. #### Buffer Period @@ -199,11 +199,11 @@ Because scheduled tasks trigger on a configured cadence, buffer periods are disa CTS will attempt to execute each enabled task once upon startup to synchronize infrastructure with the current state of Consul. The daemon will stop and exit if any error occurs while preparing the automation environment or executing a task for the first time. This helps ensure tasks have proper configuration and are executable before the daemon transitions into running tasks in full automation as service changes are discovered over time. As a result, it is not recommended to configure a task as disabled from the start. After all tasks have successfully executed once, task failures during automation will be logged and retried or attempted again after a subsequent change. -Tasks are executed near-real time when service changes are detected. For services or environments that are prone to flapping, it may be useful to configure a [buffer period](/docs/nia/configuration#buffer_period-1) for a task to accumulate changes before it is executed. The buffer period would reduce the number of consecutive network calls to infrastructure by batching changes for a task over a short duration of time. +Tasks are executed near-real time when service changes are detected. For services or environments that are prone to flapping, it may be useful to configure a [buffer period](/consul/docs/nia/configuration#buffer_period-1) for a task to accumulate changes before it is executed. The buffer period would reduce the number of consecutive network calls to infrastructure by batching changes for a task over a short duration of time. ## Status Information -Status-related information is collected and offered via [status API](/docs/nia/api#status) to provide visibility into what and how the tasks are running. Information is offered in three-levels (lowest to highest): +Status-related information is collected and offered via [status API](/consul/docs/nia/api#status) to provide visibility into what and how the tasks are running. Information is offered in three-levels (lowest to highest): - Event data - Task status @@ -233,7 +233,7 @@ Sample event: } ``` -For complete information on the event structure, see [events in our API documentation](/docs/nia/api#event). Event information can be retrieved by using the [`include=events` parameter](/docs/nia/api#include) with the [task status API](/docs/nia/api#task-status). +For complete information on the event structure, see [events in our API documentation](/consul/docs/nia/api#event). Event information can be retrieved by using the [`include=events` parameter](/consul/docs/nia/api#include) with the [task status API](/consul/docs/nia/api#task-status). ### Task Status @@ -251,7 +251,7 @@ Sample task status: } ``` -Task status information can be retrieved with [task status API](/docs/nia/api#task-status). The API documentation includes details on what health statuses are available and how it is calculated based on events' success/failure information. +Task status information can be retrieved with [task status API](/consul/docs/nia/api#task-status). The API documentation includes details on what health statuses are available and how it is calculated based on events' success/failure information. ### Overall Status @@ -269,4 +269,4 @@ Sample overall status: } ``` -Overall status information can be retrieved with [overall status API](/docs/nia/api#overall-status). The API documentation includes details on what health statuses are available and how it is calculated based on task statuses' health status information. +Overall status information can be retrieved with [overall status API](/consul/docs/nia/api#overall-status). The API documentation includes details on what health statuses are available and how it is calculated based on task statuses' health status information. diff --git a/website/content/docs/nia/terraform-modules.mdx b/website/content/docs/nia/terraform-modules.mdx index 2ecc8665b0..8e041de79b 100644 --- a/website/content/docs/nia/terraform-modules.mdx +++ b/website/content/docs/nia/terraform-modules.mdx @@ -11,7 +11,7 @@ Consul-Terraform-Sync (CTS) automates execution of Terraform modules through tas ## Module Specifications -Compatible modules for CTS follow the [standard module](https://www.terraform.io/language/modules/develop#module-structure) structure. Modules can use syntax supported by Terraform version 0.13 and newer. +Compatible modules for CTS follow the [standard module](/terraform/language/modules/develop#module-structure) structure. Modules can use syntax supported by Terraform version 0.13 and newer. ### Compatibility Requirements @@ -31,20 +31,20 @@ See below sections for more information on [defining module input](#module-input ### Module Input ((#source-input)) -A task monitors [Consul objects](/docs/nia#consul-objects) that are defined by the task's configuration. The Consul objects can be used for the module input that satisfies the requirements defined by the task's Terraform module's [input variables](https://www.terraform.io/language/values/variables). +A task monitors [Consul objects](/consul/docs/nia#consul-objects) that are defined by the task's configuration. The Consul objects can be used for the module input that satisfies the requirements defined by the task's Terraform module's [input variables](/terraform/language/values/variables). A task's module input is slightly different from the task's condition, even though both monitor defined objects. The task's condition monitors defined objects with a configured criteria. When this criteria is satisfied, the task will trigger. The module input, however, monitors defined objects with the intent of providing values or metadata about these objects to the Terraform module. The monitored module input and condition objects can be the same object, such as a task configured with a `condition "services"` block and `use_as_module_input` set to `true`. The module input and condition can also be different objects and configured separately, such as a task configured with a `condition "catalog-services` and `module_input "consul-kv"` block. As a result, the monitored module input is decoupled from the provided condition in order to satisfy the Terraform module. -Each type of object that CTS monitors can only be defined through one configuration within a task definition. For example, if a task monitors services, the task cannot have both `condition "services"` and `module_input "services"` configured. See [Task Module Input configuration](/docs/nia/configuration#task-module-input) for more details. +Each type of object that CTS monitors can only be defined through one configuration within a task definition. For example, if a task monitors services, the task cannot have both `condition "services"` and `module_input "services"` configured. See [Task Module Input configuration](/consul/docs/nia/configuration#task-module-input) for more details. There are a few ways that a module input can be defined: -- [**`services` list**](/docs/nia/configuration#services) (deprecated) - The list of services to use as module input. +- [**`services` list**](/consul/docs/nia/configuration#services) (deprecated) - The list of services to use as module input. - **`condition` block's `use_as_module_input` field** - When set to true, the condition's objects are used as module input. - Field was previously named `source_includes_var` (deprecated) -- [**`module_input` blocks**](/docs/nia/configuration#module-input) - This block can be configured multiple times to define objects to use as module input. +- [**`module_input` blocks**](/consul/docs/nia/configuration#module-input) - This block can be configured multiple times to define objects to use as module input. - Block was previously named `source_input` (deprecated) Multiple ways of defining a module input adds configuration flexibility, and allows for optional additional input variables to be supported by CTS alongside the `services` input variable. @@ -95,13 +95,13 @@ services = { In order to configure a task with the services module input, the list of services that will be used for the input must be configured in one of the following ways: -- the task's [`services`](/docs/nia/configuration#services) (deprecated) -- a [`condition "services"` block](/docs/nia/configuration#services-condition) configured with `use_as_module_input` field set to true +- the task's [`services`](/consul/docs/nia/configuration#services) (deprecated) +- a [`condition "services"` block](/consul/docs/nia/configuration#services-condition) configured with `use_as_module_input` field set to true - Field was previously named `source_includes_var` (deprecated) -- a [`module_input "services"` block](/docs/nia/configuration#services-module-input) +- a [`module_input "services"` block](/consul/docs/nia/configuration#services-module-input) - Block was previously named `source_input "services"` (deprecated) -The services module input operates by monitoring the [Health List Nodes For Service API](/api-docs/health#list-nodes-for-service) and provides the latest service information to the input variables. A complete list of service information that would be provided to the module is expanded below: +The services module input operates by monitoring the [Health List Nodes For Service API](/consul/api-docs/health#list-nodes-for-service) and provides the latest service information to the input variables. A complete list of service information that would be provided to the module is expanded below: | Attribute | Description | | ----------------------- | ------------------------------------------------------------------------------------------------- | @@ -139,7 +139,7 @@ task { #### Consul KV Module Input ((#consul-kv-source-input)) -Tasks configured with a Consul KV module input monitor Consul KV for changes to KV pairs that satisfy the provided configuration. The Consul KV module input operates by monitoring the [Consul KV API](/api-docs/kv#read-key) and provides these key values to the task's module. +Tasks configured with a Consul KV module input monitor Consul KV for changes to KV pairs that satisfy the provided configuration. The Consul KV module input operates by monitoring the [Consul KV API](/consul/api-docs/kv#read-key) and provides these key values to the task's module. Sample rendered consul KV input: @@ -155,12 +155,12 @@ consul_kv = { To configure a task with the Consul KV module input, the KVs which will be used for the input must be configured in one of the following ways: -- a [`condition "consul-kv"` block](/docs/nia/configuration#consul-kv-condition) configured with the `use_as_module_input` field set to true. +- a [`condition "consul-kv"` block](/consul/docs/nia/configuration#consul-kv-condition) configured with the `use_as_module_input` field set to true. - Field was previously named `source_includes_var` (deprecated) -- a [`module_input "consul-kv"` block](/docs/nia/configuration#consul-kv-module-input). +- a [`module_input "consul-kv"` block](/consul/docs/nia/configuration#consul-kv-module-input). - Block was previously named `source_input "consul-kv"` (deprecated) -Below is a similar example to the one provided in the [Consul KV Condition](/docs/nia/tasks#consul-kv-condition) section. However, the difference in this example is that instead of triggering based on a change to Consul KV, this task will instead execute on a schedule. Once execution is triggered, Consul KV information is then provided to the task's module. +Below is a similar example to the one provided in the [Consul KV Condition](/consul/docs/nia/tasks#consul-kv-condition) section. However, the difference in this example is that instead of triggering based on a change to Consul KV, this task will instead execute on a schedule. Once execution is triggered, Consul KV information is then provided to the task's module. ```hcl task { @@ -183,7 +183,7 @@ task { #### Catalog Services Module Input ((#catalog-services-source-input)) -Tasks configured with a Catalog Services module input monitors for service and tag information provided by the [Catalog List Services API](/api-docs/catalog#list-services). The module input is a map of service names to a list of tags. +Tasks configured with a Catalog Services module input monitors for service and tag information provided by the [Catalog List Services API](/consul/api-docs/catalog#list-services). The module input is a map of service names to a list of tags. Sample rendered catalog-services input: @@ -201,7 +201,7 @@ catalog_services = { To configure a task with the Catalog Services module input, the catalog services which will be used for the input must be configured in one of the following ways: -- a [`condition "catalog-services"` block](/docs/nia/configuration#consul-kv-condition) configured with `use_as_module_input` field. +- a [`condition "catalog-services"` block](/consul/docs/nia/configuration#consul-kv-condition) configured with `use_as_module_input` field. - Field was previously named `source_includes_var` (deprecated) -> **Note:** Currently there is no support for a `module_input "catalog-services"` block. @@ -228,7 +228,7 @@ task { ## How to Create a Compatible Terraform Module -You can read more on how to [create a module](https://www.terraform.io/language/modules/develop) or work through a [tutorial to build a module](https://learn.hashicorp.com/tutorials/terraform/module-create?utm_source=docs). CTS is designed to integrate with any module that satisfies the specifications in the following section. +You can read more on how to [create a module](/terraform/language/modules/develop) or work through a [tutorial to build a module](/terraform/tutorials/modules/module-create?utm_source=docs). CTS is designed to integrate with any module that satisfies the specifications in the following section. The repository [hashicorp/consul-terraform-sync-template-module](https://github.com/hashicorp/consul-terraform-sync-template-module) can be cloned and used as a starting point for structuring a compatible Terraform module. The template repository has the files described in the next steps prepared. @@ -250,11 +250,11 @@ resource "local_file" "consul_services" {     -Something important to consider before authoring your module is deciding the [condition under which it will execute](/docs/nia/tasks#task-execution). This will allow you to potentially use other types of CTS provided input variables in your module. It will also help inform your documentation and how users should configure their task for your module. +Something important to consider before authoring your module is deciding the [condition under which it will execute](/consul/docs/nia/tasks#task-execution). This will allow you to potentially use other types of CTS provided input variables in your module. It will also help inform your documentation and how users should configure their task for your module. ### Services Variable -To satisfy the specification requirements for a compatible module, copy the `services` variable declaration to the `variables.tf` file. Your module can optionally have other [variable declarations](#module-input-variables) and [CTS provided input variables](/docs/nia/terraform-modules#optional-input-variables) in addition to `var.services`. +To satisfy the specification requirements for a compatible module, copy the `services` variable declaration to the `variables.tf` file. Your module can optionally have other [variable declarations](#module-input-variables) and [CTS provided input variables](/consul/docs/nia/terraform-modules#optional-input-variables) in addition to `var.services`. @@ -288,9 +288,9 @@ variable "services" { -Keys of the `services` map are unique identifiers of the service across Consul agents and data centers. Keys follow the format `service-id.node.datacenter` (or `service-id.node.namespace.datacenter` for Consul Enterprise). A complete list of attributes available for the `services` variable is included in the [documentation for CTS tasks](/docs/nia/tasks#services-condition). +Keys of the `services` map are unique identifiers of the service across Consul agents and data centers. Keys follow the format `service-id.node.datacenter` (or `service-id.node.namespace.datacenter` for Consul Enterprise). A complete list of attributes available for the `services` variable is included in the [documentation for CTS tasks](/consul/docs/nia/tasks#services-condition). -Terraform variables when passed as module arguments can be [lossy for object types](https://www.terraform.io/language/expressions/type-constraints#conversion-of-complex-types). This allows CTS to declare the full variable with every object attribute in the generated root module, and pass the variable to a child module that contains a subset of these attributes for its variable declaration. Modules compatible with CTS may simplify the `var.services` declaration within the module by omitting unused attributes. For example, the following services variable has 4 attributes with the rest omitted. +Terraform variables when passed as module arguments can be [lossy for object types](/terraform/language/expressions/type-constraints#conversion-of-complex-types). This allows CTS to declare the full variable with every object attribute in the generated root module, and pass the variable to a child module that contains a subset of these attributes for its variable declaration. Modules compatible with CTS may simplify the `var.services` declaration within the module by omitting unused attributes. For example, the following services variable has 4 attributes with the rest omitted. @@ -313,7 +313,7 @@ variable "services" { ### Catalog Services Variable -If you are creating a module for a [catalog-services condition](/docs/nia/tasks#catalog-services-condition), then you have the option to add the `catalog_services` variable, which contains service registration and tag information. If your module would benefit from consuming this information, you can copy the `catalog_services` variable declaration to your `variables.tf` file in addition to the other variables. +If you are creating a module for a [catalog-services condition](/consul/docs/nia/tasks#catalog-services-condition), then you have the option to add the `catalog_services` variable, which contains service registration and tag information. If your module would benefit from consuming this information, you can copy the `catalog_services` variable declaration to your `variables.tf` file in addition to the other variables. @@ -328,13 +328,13 @@ variable "catalog_services" { The keys of the `catalog_services` map are the names of the services that are registered with Consul at the given datacenter. The value for each service name is a list of all known tags for that service. -We recommend that if you make a module with with a catalog-services condition, that you document this in the README. This way, users that want to configure a task with your module will know to configure a catalog-services [condition](/docs/nia/configuration#condition) block. +We recommend that if you make a module with with a catalog-services condition, that you document this in the README. This way, users that want to configure a task with your module will know to configure a catalog-services [condition](/consul/docs/nia/configuration#condition) block. -Similarly, if you use the `catalog_services` variable in your module, we recommend that you also document this usage in the README. Users of your module will then know to set the catalog-services condition [`use_as_module_input`](/docs/nia/configuration#catalog-services-condition) configuration to be true. When this field is set to true, CTS will declare the `catalog_services` variable in the generated root module, and pass the variable to a child module. Therefore, if this field is configured inconsistently, CTS will error and exit. +Similarly, if you use the `catalog_services` variable in your module, we recommend that you also document this usage in the README. Users of your module will then know to set the catalog-services condition [`use_as_module_input`](/consul/docs/nia/configuration#catalog-services-condition) configuration to be true. When this field is set to true, CTS will declare the `catalog_services` variable in the generated root module, and pass the variable to a child module. Therefore, if this field is configured inconsistently, CTS will error and exit. ### Consul KV Variable -If you are creating a module for a [consul-kv condition](/docs/nia/tasks#consul-kv-condition), then you have the option to add the `consul_kv` variable, which contains a map of the keys and values for the Consul KV pairs. If your module would benefit from consuming this information, you can copy the `consul_kv` variable declaration to your `variables.tf` file in addition to the other variables. +If you are creating a module for a [consul-kv condition](/consul/docs/nia/tasks#consul-kv-condition), then you have the option to add the `consul_kv` variable, which contains a map of the keys and values for the Consul KV pairs. If your module would benefit from consuming this information, you can copy the `consul_kv` variable declaration to your `variables.tf` file in addition to the other variables. @@ -347,19 +347,19 @@ variable "consul_kv" { -If your module contains the `consul_kv` variable, we recommend documenting the usage in the README file so that users know to set the [`use_as_module_input`](/docs/nia/configuration#consul-kv-condition) configuration to `true` in the `consul-kv` condition. Setting the field to `true` instructs CTS to declare the `consul_kv` variable in the generated root module and pass the variable to a child module. Therefore, if this field is configured inconsistently, CTS will error and exit. +If your module contains the `consul_kv` variable, we recommend documenting the usage in the README file so that users know to set the [`use_as_module_input`](/consul/docs/nia/configuration#consul-kv-condition) configuration to `true` in the `consul-kv` condition. Setting the field to `true` instructs CTS to declare the `consul_kv` variable in the generated root module and pass the variable to a child module. Therefore, if this field is configured inconsistently, CTS will error and exit. ### Module Input Variables -Network infrastructure differs vastly across teams and organizations, and the automation needs of practitioners are unique based on their existing setup. [Input variables](https://www.terraform.io/language/values/variables) can be used to serve as customization parameters to the module for practitioners. +Network infrastructure differs vastly across teams and organizations, and the automation needs of practitioners are unique based on their existing setup. [Input variables](/terraform/language/values/variables) can be used to serve as customization parameters to the module for practitioners. 1. Identify areas in the module where practitioners could tailor the automation to fit their infrastructure. 2. Declare input variables and insert the use of variables throughout module resources to expose these options to practitioners. -3. Include descriptions to capture what the variables are and how they are used, and specify [custom validation rules for variables](https://www.terraform.io/language/values/variables#custom-validation-rules) to provide context to users the expected format and conditions for the variables. +3. Include descriptions to capture what the variables are and how they are used, and specify [custom validation rules for variables](/terraform/language/values/variables#custom-validation-rules) to provide context to users the expected format and conditions for the variables. 4. Set reasonable default values for variables that are optional, or omit default values for variables that are required module arguments. -5. Set the [sensitive argument](https://www.terraform.io/language/values/variables) for variables that contain secret or sensitive values. When set, Terraform will redact the value from output when Terraform commands are run. +5. Set the [sensitive argument](/terraform/language/values/variables) for variables that contain secret or sensitive values. When set, Terraform will redact the value from output when Terraform commands are run. -Terraform is an explicit configuration language and requires variables to be declared, typed, and passed explicitly through as module arguments. CTS abstracts this by creating intermediate variables at the root level from the module input. These values are configured by practitioners within the [`task` block](/docs/nia/configuration#variable_files). Value assignments are parsed to interpolate the corresponding variable declaration and are written to the appropriate Terraform files. A few assumptions are made for the intermediate variables: the variables users provide CTS are declared and supported by the module, matching name and type. +Terraform is an explicit configuration language and requires variables to be declared, typed, and passed explicitly through as module arguments. CTS abstracts this by creating intermediate variables at the root level from the module input. These values are configured by practitioners within the [`task` block](/consul/docs/nia/configuration#variable_files). Value assignments are parsed to interpolate the corresponding variable declaration and are written to the appropriate Terraform files. A few assumptions are made for the intermediate variables: the variables users provide CTS are declared and supported by the module, matching name and type. ### Module Guidelines @@ -375,7 +375,7 @@ Consider authoring modules with low complexity to reduce the run time for Terraf #### Providers -The Terraform module must declare which providers it requires within the [`terraform.required_providers` block](https://www.terraform.io/language/providers/requirements#requiring-providers). We suggest to also include a version constraint for the provider to specify which versions the module is compatible with. +The Terraform module must declare which providers it requires within the [`terraform.required_providers` block](/terraform/language/providers/requirements#requiring-providers). We suggest to also include a version constraint for the provider to specify which versions the module is compatible with. Aside from the `required_providers` block, provider configurations should not be included within the sharable module for network integrations. End users will configure the providers through CTS, and CTS will then translate provider configuration to the generated root module appropriately. diff --git a/website/content/docs/nia/usage/errors-ref.mdx b/website/content/docs/nia/usage/errors-ref.mdx index 0b24a1189a..fafb9faf1e 100644 --- a/website/content/docs/nia/usage/errors-ref.mdx +++ b/website/content/docs/nia/usage/errors-ref.mdx @@ -11,13 +11,13 @@ This topic explains error messages you may encounter when using Consul-Terraform ## Example error log messages -If you configured the CTS cluster to run in [high availability mode](/docs/nia/usage/run-ha) and the the local module is missing, then the following message appears in the log: +If you configured the CTS cluster to run in [high availability mode](/consul/docs/nia/usage/run-ha) and the the local module is missing, then the following message appears in the log: ```shell-session [ERROR] ha.compat: error="compatibility check failure: stat ./example-module: no such file or directory" ``` -The resolution is to add the missing local module on the incompatible CTS instance. Refer to the [`module` documentation](/docs/nia/configuration#module) in the CTS configuration reference for additional information. +The resolution is to add the missing local module on the incompatible CTS instance. Refer to the [`module` documentation](/consul/docs/nia/configuration#module) in the CTS configuration reference for additional information. ## Example API and CLI error messages @@ -67,7 +67,7 @@ $ curl --request GET cts-01.example.com:8558/v1/tasks **Resolution**: -Identify the leader instance address and redirect the request to the leader. You can identify the leader by calling the [`status/cluster` API endpoint](/docs/nia/api/status#cluster-status) or by checking the logs for the following entry: +Identify the leader instance address and redirect the request to the leader. You can identify the leader by calling the [`status/cluster` API endpoint](/consul/docs/nia/api/status#cluster-status) or by checking the logs for the following entry: ```shell-session [INFO] ha: acquired leadership lock: id=. @@ -95,7 +95,7 @@ We recommend deploying a cluster that has three instances. **Resolution**: -Identify and send the request to the leader CTS instance. You can identify the leader by calling the [`status/cluster` API endpoint](/docs/nia/api/status#cluster-status) or by checking the logs for the following entry: +Identify and send the request to the leader CTS instance. You can identify the leader by calling the [`status/cluster` API endpoint](/consul/docs/nia/api/status#cluster-status) or by checking the logs for the following entry: ```shell-session [INFO] ha: acquired leadership lock: id= @@ -115,11 +115,11 @@ Identify and send the request to the leader CTS instance. You can identify the l **Conditions**: -- You called the [`status/cluster` API endpoint](/docs/nia/api/status#cluster-status) without configuring CTS for [high availability](/docs/nia/usage/run-ha). +- You called the [`status/cluster` API endpoint](/consul/docs/nia/api/status#cluster-status) without configuring CTS for [high availability](/consul/docs/nia/usage/run-ha). **Resolution**: -Configure CTS to run in [high availability mode](/docs/nia/usage/run-ha). +Configure CTS to run in [high availability mode](/consul/docs/nia/usage/run-ha). --- diff --git a/website/content/docs/nia/usage/requirements.mdx b/website/content/docs/nia/usage/requirements.mdx index 8da0ab164a..1950b84fb2 100644 --- a/website/content/docs/nia/usage/requirements.mdx +++ b/website/content/docs/nia/usage/requirements.mdx @@ -15,7 +15,7 @@ The following components are required to run Consul-Terraform-Sync (CTS): You can add support for your network infrastructure through Terraform providers so that you can apply Terraform modules to implement network integrations. -The following guidance is for running CTS using the Terraform driver. The Terraform Cloud driver has [additional prerequisites](/docs/nia/network-drivers/terraform-cloud#setting-up-terraform-cloud-driver). +The following guidance is for running CTS using the Terraform driver. The Terraform Cloud driver has [additional prerequisites](/consul/docs/nia/network-drivers/terraform-cloud#setting-up-terraform-cloud-driver). ## Run a Consul cluster @@ -25,19 +25,19 @@ Below are several steps towards a minimum Consul setup required for running CTS. CTS is a daemon that runs alongside Consul, similar to other Consul ecosystem tools like Consul Template. CTS is not included with the Consul binary and needs to be installed separately. -To install a local Consul agent, refer to the [Getting Started: Install Consul Tutorial](https://developer.hashicorp.com/consul/tutorials/get-started-vms?utm_source=docs). +To install a local Consul agent, refer to the [Getting Started: Install Consul Tutorial](/consul/tutorials/get-started-vms?utm_source=docs). -For information on compatible Consul versions, refer to the [Consul compatibility matrix](/docs/nia/compatibility#consul). +For information on compatible Consul versions, refer to the [Consul compatibility matrix](/consul/docs/nia/compatibility#consul). ### Run an agent -The Consul agent must be running in order to dynamically update network devices. Refer to the [Consul agent documentation](/docs/agent) for information about configuring and starting a Consul agent. For hands-on instructions about running Consul agents, refer to the [Getting Started: Run the Consul Agent Tutorial](https://learn.hashicorp.com/tutorials/consul/get-started-agent?in=consul/getting-started). +The Consul agent must be running in order to dynamically update network devices. Refer to the [Consul agent documentation](/consul/docs/agent) for information about configuring and starting a Consul agent. For hands-on instructions about running Consul agents, refer to the [Getting Started: Run the Consul Agent Tutorial](/consul/tutorials/getting-started/get-started-agent). -When running a Consul agent with CTS in production, consider that CTS uses [blocking queries](/api-docs/features/blocking) to monitor task dependencies, such as changes to registered services. This results in multiple long-running TCP connections between CTS and the agent to poll changes for each dependency. Consul may quickly reach the agent connection limits if CTS is monitoring a high number of services. +When running a Consul agent with CTS in production, consider that CTS uses [blocking queries](/consul/api-docs/features/blocking) to monitor task dependencies, such as changes to registered services. This results in multiple long-running TCP connections between CTS and the agent to poll changes for each dependency. Consul may quickly reach the agent connection limits if CTS is monitoring a high number of services. -To avoid reaching the limit prematurely, we recommend using HTTP/2 (requires HTTPS) to communicate between CTS and the Consul agent. When using HTTP/2, CTS establishes a single connection and reuses it for all communication. Refer to the [Consul Configuration section](/docs/nia/configuration#consul) for details. +To avoid reaching the limit prematurely, we recommend using HTTP/2 (requires HTTPS) to communicate between CTS and the Consul agent. When using HTTP/2, CTS establishes a single connection and reuses it for all communication. Refer to the [Consul Configuration section](/consul/docs/nia/configuration#consul) for details. -Alternatively, you can configure the [`limits.http_max_conns_per_client`](/docs/agent/config/config-files#http_max_conns_per_client) option to set a maximimum number of connections to meet your needs. +Alternatively, you can configure the [`limits.http_max_conns_per_client`](/consul/docs/agent/config/config-files#http_max_conns_per_client) option to set a maximimum number of connections to meet your needs. ### Register services @@ -58,19 +58,19 @@ $ curl --request PUT --data @payload.json http://localhost:8500/v1/agent/service The example represents a non-existent web service running at `10.10.10.10:8000` that is now available for CTS to consume. -You can configure CTS to monitor the web service, execute a task, and update network device(s) by configuring `web` in the [`condition "services"`](/docs/nia/configuration#services-condition) task block. If the web service has any non-default values, it can also be configured in `condition "services"`. +You can configure CTS to monitor the web service, execute a task, and update network device(s) by configuring `web` in the [`condition "services"`](/consul/docs/nia/configuration#services-condition) task block. If the web service has any non-default values, it can also be configured in `condition "services"`. -For more details on registering a service using the HTTP API endpoint, refer to the [register service API docs](/api-docs/agent/service#register-service). +For more details on registering a service using the HTTP API endpoint, refer to the [register service API docs](/consul/api-docs/agent/service#register-service). -For hands-on instructions on registering a service by loading a service definition, refer to the [Getting Started: Register a Service with Consul Service Discovery Tutorial](https://learn.hashicorp.com/tutorials/consul/get-started-service-discovery?in=consul/getting-started). +For hands-on instructions on registering a service by loading a service definition, refer to the [Getting Started: Register a Service with Consul Service Discovery Tutorial](/consul/tutorials/getting-started/get-started-service-discovery). ### Run a cluster -For production environments, we recommend operating a Consul cluster rather than a single agent. Refer to [Getting Started: Create a Local Consul Datacenter](https://learn.hashicorp.com/tutorials/consul/get-started-create-datacenter?in=consul/getting-started) for instructions on starting multiple Consul agents and joining them into a cluster. +For production environments, we recommend operating a Consul cluster rather than a single agent. Refer to [Getting Started: Create a Local Consul Datacenter](/consul/tutorials/getting-started/get-started-create-datacenter) for instructions on starting multiple Consul agents and joining them into a cluster. ## Network infrastructure using a Terraform provider -CTS integrations for the Terraform driver use Terraform providers as plugins to interface with specific network infrastructure platforms. The Terraform driver for CTS inherits the expansive collection of Terraform providers to integrate with. You can also specify a provider `source` in the [`required_providers` configuration](https://www.terraform.io/language/providers/requirements#requiring-providers) to use providers written by the community (requires Terraform 0.13 or later). +CTS integrations for the Terraform driver use Terraform providers as plugins to interface with specific network infrastructure platforms. The Terraform driver for CTS inherits the expansive collection of Terraform providers to integrate with. You can also specify a provider `source` in the [`required_providers` configuration](/terraform/language/providers/requirements#requiring-providers) to use providers written by the community (requires Terraform 0.13 or later). ### Finding Terraform providers @@ -80,16 +80,16 @@ To find providers for the infrastructure platforms you use, browse the providers If a Terraform provider does not exist for your environment, you can create a new Terraform provider and publish it to the registry so that you can use it within a network integration task or create a compatible Terraform module. Refer to the following Terraform tutorial and documentation for additional information on creating and publishing providers: -- [Setup and Implement Read](https://learn.hashicorp.com/tutorials/terraform/provider-setup) -- [Publishing Providers](https://www.terraform.io/registry/providers/publishing). +- [Setup and Implement Read](/terraform/tutorials/providers/provider-setup) +- [Publishing Providers](/terraform/registry/providers/publishing). ## Network integration using a Terraform module The Terraform module for a task in CTS is the core component of the integration. It declares which resources to use and how your infrastructure is dynamically updated. The module, along with how it is configured within a task, determines the conditions under which your infrastructure is updated. -Working with a Terraform provider, you can write an integration task for CTS by [creating a Terraform module](/docs/nia/terraform-modules) that is compatible with the Terraform driver. You can also use a [module built by partners](#partner-terraform-modules). +Working with a Terraform provider, you can write an integration task for CTS by [creating a Terraform module](/consul/docs/nia/terraform-modules) that is compatible with the Terraform driver. You can also use a [module built by partners](#partner-terraform-modules). -Refer to [Configuration](/docs/nia/configuration) for information about configuring CTS and how to use Terraform providers and modules for tasks. +Refer to [Configuration](/consul/docs/nia/configuration) for information about configuring CTS and how to use Terraform providers and modules for tasks. ### Partner Terraform Modules diff --git a/website/content/docs/nia/usage/run-ha.mdx b/website/content/docs/nia/usage/run-ha.mdx index 81fa5c2d16..1623cd66ce 100644 --- a/website/content/docs/nia/usage/run-ha.mdx +++ b/website/content/docs/nia/usage/run-ha.mdx @@ -33,15 +33,15 @@ The following diagram shows the CTS cluster state after the leader stops. CTS In - The time it takes for a new leader to be elected is determined by the `high_availability.cluster.storage.session_ttl` configuration. The minimum failover time is equal to the `session_ttl` value. The maximum failover time is double the `session_ttl` value. - If failover occurs during task execution, a new leader is elected. The new leader will attempt to run all tasks once before continuing to monitor for changes. -- If using the [Terraform Cloud (TFC) driver](/docs/nia/network-drivers/terraform-cloud), the task finishes and CTS starts a new leader that attempts to queue a run for each task in TFC in once-mode. -- If using [Terraform driver](/docs/nia/network-drivers/terraform), the task may complete depending on the cause of the failover. The new leader starts and attempts to run each task in [once-mode](/docs/nia/cli/start#modes). Depending on the module and provider, the task may require manual intervention to fix any inconsistencies between the infrastructure and Terraform state. +- If using the [Terraform Cloud (TFC) driver](/consul/docs/nia/network-drivers/terraform-cloud), the task finishes and CTS starts a new leader that attempts to queue a run for each task in TFC in once-mode. +- If using [Terraform driver](/consul/docs/nia/network-drivers/terraform), the task may complete depending on the cause of the failover. The new leader starts and attempts to run each task in [once-mode](/consul/docs/nia/cli/start#modes). Depending on the module and provider, the task may require manual intervention to fix any inconsistencies between the infrastructure and Terraform state. - If failover occurs when no task is executing, CTS elects a new leader that attempts to run all tasks in once-mode. Note that driver behavior is consistent whether or not CTS is running in high availability mode. ## Requirements -Verify that you have met the [basic requirements](/docs/nia/usage/requirements) for running CTS. +Verify that you have met the [basic requirements](/consul/docs/nia/usage/requirements) for running CTS. * CTS Enterprise 0.7 or later * Terraform CLI 0.13 or later @@ -49,11 +49,11 @@ Verify that you have met the [basic requirements](/docs/nia/usage/requirements) You must configure appropriate ACL permissions for your cluster. Refer to [ACL permissions](#) for details. -We recommend specifying the [TFC driver](/docs/nia/network-drivers/terraform-cloud) in your CTS configuration if you want to run in high availability mode. +We recommend specifying the [TFC driver](/consul/docs/nia/network-drivers/terraform-cloud) in your CTS configuration if you want to run in high availability mode. ## Configuration -Add the `high_availability` block in your CTS configuration and configure the required settings to enable high availability. Refer to the [Configuration reference](/docs/nia/configuration#high-availability) for details about the configuration fields for the `high_availability` block. +Add the `high_availability` block in your CTS configuration and configure the required settings to enable high availability. Refer to the [Configuration reference](/consul/docs/nia/configuration#high-availability) for details about the configuration fields for the `high_availability` block. The following example configures high availability functionality for a cluster named `cts-cluster`: @@ -79,7 +79,7 @@ high_availability { ### ACL permissions -The `session` and `keys` resources in your Consul environment must have `write` permissions. Refer to the [ACL documentation](/docs/security/acl) for details on how to define ACL policies. +The `session` and `keys` resources in your Consul environment must have `write` permissions. Refer to the [ACL documentation](/consul/docs/security/acl) for details on how to define ACL policies. If the `high_availability.cluster.storage.namespace` field is configured, then your ACL policy must also enable `write` permissions for the `namespace` resource. @@ -87,12 +87,12 @@ If the `high_availability.cluster.storage.namespace` field is configured, then y We recommend deploying a cluster that includes three CTS instances. This is so that the cluster has one leader and two followers. -1. Create an HCL configuration file that includes the settings you want to include, including the `high_availability` block. Refer to [Configuration Options for Consul-Terraform-Sync](/docs/nia/configuration) for all configuration options. -1. Issue the startup command and pass the configuration file. Refer to the [`start` command reference](/docs/nia/cli/start#modes) for additional information about CTS startup modes. +1. Create an HCL configuration file that includes the settings you want to include, including the `high_availability` block. Refer to [Configuration Options for Consul-Terraform-Sync](/consul/docs/nia/configuration) for all configuration options. +1. Issue the startup command and pass the configuration file. Refer to the [`start` command reference](/consul/docs/nia/cli/start#modes) for additional information about CTS startup modes. ```shell-session $ consul-terraform-sync start -config-file ha-config.hcl ``` -1. You can call the `/status` API endpoint to verify the status of tasks CTS is configured to monitor. Only the leader of the cluster will return a successful response. Refer to the [`/status` API reference documentation](/docs/nia/api/status) for information about usage and responses. +1. You can call the `/status` API endpoint to verify the status of tasks CTS is configured to monitor. Only the leader of the cluster will return a successful response. Refer to the [`/status` API reference documentation](/consul/docs/nia/api/status) for information about usage and responses. ```shell-session $ curl localhost:/status/tasks @@ -104,7 +104,7 @@ Repeat the procedure to start the remaining instances for your cluster. We recom You can implement a rolling update to update a non-task configuration for a CTS instance, such as the Consul connection settings. If you need to update a task in the instance configuration, refer to [Modify tasks](#modify-tasks). -1. Identify the leader CTS instance by either making a call to the [`status/cluster` API endpoint](/docs/nia/api/status#cluster-status) or by checking the logs for the following entry: +1. Identify the leader CTS instance by either making a call to the [`status/cluster` API endpoint](/consul/docs/nia/api/status#cluster-status) or by checking the logs for the following entry: ```shell-session [INFO] ha: acquired leadership lock: id= ``` @@ -116,7 +116,7 @@ You can implement a rolling update to update a non-task configuration for a CTS ## Modify tasks -When high availability is enabled, CTS persists task and event data. Refer to [State storage and persistence](/docs/nia/architecture#state-storage-and-persistence) for additional information. +When high availability is enabled, CTS persists task and event data. Refer to [State storage and persistence](/consul/docs/nia/architecture#state-storage-and-persistence) for additional information. You can use the following methods for modifying tasks when high availability is enabled. We recommend choosing a single method to make all task configuration changes because inconsistencies between the state and the configuration can occur when mixing methods. @@ -124,18 +124,18 @@ You can use the following methods for modifying tasks when high availability is Use the CTS API to identify the CTS leader instance as well as delete and replace a task. -1. Identify the leader CTS instance by either making a call to the [`status/cluster` API endpoint](/docs/nia/api/status#cluster-status) or by checking the logs for the following entry: +1. Identify the leader CTS instance by either making a call to the [`status/cluster` API endpoint](/consul/docs/nia/api/status#cluster-status) or by checking the logs for the following entry: ```shell-session [INFO] ha: acquired leadership lock: id= ``` -1. Send a `DELETE` call to the [`/task/` endpoint](/docs/nia/api/tasks#delete-task) to delete the task. In the following example, the leader instance is at `localhost:8558`: +1. Send a `DELETE` call to the [`/task/` endpoint](/consul/docs/nia/api/tasks#delete-task) to delete the task. In the following example, the leader instance is at `localhost:8558`: ```shell-session $ curl --request DELETE localhost:8558/v1/tasks/task_a ``` - You can also use the [`task delete` command](/docs/nia/cli/task#task-delete) to complete this step. + You can also use the [`task delete` command](/consul/docs/nia/cli/task#task-delete) to complete this step. 1. Send a `POST` call to the `/task/` endpoint and include the updated task in your payload. ```shell-session @@ -145,11 +145,11 @@ Use the CTS API to identify the CTS leader instance as well as delete and replac localhost:8558/v1/tasks ``` - You can also use the [`task-create` command](/docs/nia/cli/task#task-create) to complete this step. + You can also use the [`task-create` command](/consul/docs/nia/cli/task#task-create) to complete this step. ### Discard data with the `-reset-storage` flag -You can restart the CTS cluster using the [`-reset-storage` flag](/docs/nia/cli/start#options) to discard persisted data if you need to update a task. +You can restart the CTS cluster using the [`-reset-storage` flag](/consul/docs/nia/cli/start#options) to discard persisted data if you need to update a task. 1. Stop a follower instance. 1. Update the instance’s task configuration. @@ -162,7 +162,7 @@ You can restart the CTS cluster using the [`-reset-storage` flag](/docs/nia/cli/ Use the following troubleshooting procedure if a previous leader had been running a task successfully but the new leader logs an error after a failover: -1. Check the logs printed to the console for errors. Refer to the [`syslog` configuration](/docs/nia/configuration#syslog) for information on how to locate the logs. In the following example output, CTS reported a `401: Bad credentials` error: +1. Check the logs printed to the console for errors. Refer to the [`syslog` configuration](/consul/docs/nia/configuration#syslog) for information on how to locate the logs. In the following example output, CTS reported a `401: Bad credentials` error: ```shell-session 2022-08-23T09:25:09.501-0700 [ERROR] tasksmanager: error applying task: task_name=config-task error= diff --git a/website/content/docs/nia/usage/run.mdx b/website/content/docs/nia/usage/run.mdx index ef26f96c56..43e35f09c3 100644 --- a/website/content/docs/nia/usage/run.mdx +++ b/website/content/docs/nia/usage/run.mdx @@ -7,7 +7,7 @@ description: >- # Run Consul-Terraform-Sync -This topic describes the basic procedure for running Consul-Terraform-Sync (CTS). Verify that you have met the [basic requirements](/docs/nia/usage/requirements) before attempting to run CTS. +This topic describes the basic procedure for running Consul-Terraform-Sync (CTS). Verify that you have met the [basic requirements](/consul/docs/nia/usage/requirements) before attempting to run CTS. 1. Move the `consul-terraform-sync` binary to a location available on your `PATH`. @@ -15,7 +15,7 @@ This topic describes the basic procedure for running Consul-Terraform-Sync (CTS) $ mv ~/Downloads/consul-terraform-sync /usr/local/bin/consul-terraform-sync ``` -2. Create the config.hcl file and configure the options for your use case. Refer to the [configuration reference](/docs/nia/configuration) for details about all CTS configurations. +2. Create the config.hcl file and configure the options for your use case. Refer to the [configuration reference](/consul/docs/nia/configuration) for details about all CTS configurations. 3. Run Consul-Terraform-Sync (CTS). @@ -23,7 +23,7 @@ This topic describes the basic procedure for running Consul-Terraform-Sync (CTS) $ consul-terraform-sync start -config-file ``` -4. Check status of tasks. Replace port number if configured in Step 2. Refer to [Consul-Terraform-Sync API](/docs/nia/api) for additional information. +4. Check status of tasks. Replace port number if configured in Step 2. Refer to [Consul-Terraform-Sync API](/consul/docs/nia/api) for additional information. ```shell-session $ curl localhost:8558/status/tasks @@ -31,11 +31,11 @@ This topic describes the basic procedure for running Consul-Terraform-Sync (CTS) ## Other Run modes -You can [configure CTS for high availability](/docs/nia/usage/run-ha), which is an enterprise capability that ensures that all changes to Consul that occur during a failover transition are processed and that CTS continues to operate as expected. +You can [configure CTS for high availability](/consul/docs/nia/usage/run-ha), which is an enterprise capability that ensures that all changes to Consul that occur during a failover transition are processed and that CTS continues to operate as expected. -You can start CTS in [inspect mode](/docs/nia/cli/start#modes) to review and test your configuration before applying any changes. Inspect mode allows you to verify that the changes work as expected before running them in an unsupervised daemon mode. +You can start CTS in [inspect mode](/consul/docs/nia/cli/start#modes) to review and test your configuration before applying any changes. Inspect mode allows you to verify that the changes work as expected before running them in an unsupervised daemon mode. -For hands-on instructions on using inspect mode, refer to the [Consul-Terraform-Sync Run Modes and Status Inspection](https://learn.hashicorp.com/tutorials/consul/consul-terraform-sync-run-and-inspect?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. +For hands-on instructions on using inspect mode, refer to the [Consul-Terraform-Sync Run Modes and Status Inspection](/consul/tutorials/network-infrastructure-automation/consul-terraform-sync-run-and-inspect?utm_source=WEBSITE&utm_medium=WEB_IO&utm_offer=ARTICLE_PAGE&utm_content=DOCS) tutorial. diff --git a/website/content/docs/release-notes/consul-api-gateway/v0_1_x.mdx b/website/content/docs/release-notes/consul-api-gateway/v0_1_x.mdx index 0ef5e5f663..293b3ffa83 100644 --- a/website/content/docs/release-notes/consul-api-gateway/v0_1_x.mdx +++ b/website/content/docs/release-notes/consul-api-gateway/v0_1_x.mdx @@ -68,10 +68,10 @@ This release includes the following features and capabilities: - HashiCorp Consul Helm chart 0.41.1+ - Kubernetes 1.21+ - Kubectl 1.21+ -- Envoy proxy support is determined by the Consul version deployed. Refer to [Envoy Integration](/docs/connect/proxies/envoy) for details. +- Envoy proxy support is determined by the Consul version deployed. Refer to [Envoy Integration](/consul/docs/connect/proxies/envoy) for details. ## Kubernetes Gateway API Specification Supported version of the [Gateway API](https://gateway-api.sigs.k8s.io/) spec: `v1alpha2`(v0.4.1) -For more detailed information, please refer to the [product documentation](/docs/api-gateway). +For more detailed information, please refer to the [product documentation](/consul/docs/api-gateway). diff --git a/website/content/docs/release-notes/consul-api-gateway/v0_2_x.mdx b/website/content/docs/release-notes/consul-api-gateway/v0_2_x.mdx index 0ef656cc28..20603c9ba6 100644 --- a/website/content/docs/release-notes/consul-api-gateway/v0_2_x.mdx +++ b/website/content/docs/release-notes/consul-api-gateway/v0_2_x.mdx @@ -29,7 +29,7 @@ description: >- - Kubernetes 1.21+ - Kubectl 1.21+ - Envoy proxy support is determined by the Consul version deployed. Refer to - [Envoy Integration](/docs/connect/proxies/envoy) for details. + [Envoy Integration](/consul/docs/connect/proxies/envoy) for details. ## Kubernetes Gateway API Specification @@ -39,7 +39,7 @@ Supported version of the [Gateway API](https://gateway-api.sigs.k8s.io/) spec: ` ~> **Note**: If your current deployment has routes and and services that cross namespaces, those routes will not be applied to their gateways until cross namespace reference policies are created for them. -For detailed information on upgrading, including how to create the required reference policies, please refer to the [upgrade details page](/docs/api-gateway/upgrades) +For detailed information on upgrading, including how to create the required reference policies, please refer to the [upgrade details page](/consul/docs/api-gateway/upgrades) ## Change logs diff --git a/website/content/docs/release-notes/consul-api-gateway/v0_3_x.mdx b/website/content/docs/release-notes/consul-api-gateway/v0_3_x.mdx index 660c0add56..d5b801d6fa 100644 --- a/website/content/docs/release-notes/consul-api-gateway/v0_3_x.mdx +++ b/website/content/docs/release-notes/consul-api-gateway/v0_3_x.mdx @@ -39,7 +39,7 @@ description: >- - Kubernetes 1.24 is not supported at this time. - Kubectl 1.21+ - Envoy proxy support is determined by the Consul version deployed. Refer to - [Envoy Integration](/docs/connect/proxies/envoy) for details. + [Envoy Integration](/consul/docs/connect/proxies/envoy) for details. ## Kubernetes Gateway API Specification @@ -47,7 +47,7 @@ Supported version of the [Gateway API](https://gateway-api.sigs.k8s.io/) spec: ` ## Upgrading -For detailed information on upgrading, please refer to the [upgrade details page](/docs/api-gateway/upgrades) +For detailed information on upgrading, please refer to the [upgrade details page](/consul/docs/api-gateway/upgrades) ## Changelogs diff --git a/website/content/docs/release-notes/consul-api-gateway/v0_4_x.mdx b/website/content/docs/release-notes/consul-api-gateway/v0_4_x.mdx index b0c336af72..a6e82167d3 100644 --- a/website/content/docs/release-notes/consul-api-gateway/v0_4_x.mdx +++ b/website/content/docs/release-notes/consul-api-gateway/v0_4_x.mdx @@ -31,7 +31,7 @@ description: >- to rewrite the URL path in a client's HTTP request before sending the request to a service. For example, you could configure the gateway to change the path from `//store/checkout` to `//cart/checkout`. Refer to the [usage - documentation](/docs/api-gateway/usage) for additional information. + documentation](/consul/docs/api-gateway/usage) for additional information. ## What has Changed @@ -41,7 +41,7 @@ description: >- in a future version of the standard. After upgrading to this version of Consul API Gateway, you should rename all - existing `ReferencePolicy` to `ReferenceGrant`. Refer to the [Upgrades](/docs/api-gateway/upgrades) + existing `ReferencePolicy` to `ReferenceGrant`. Refer to the [Upgrades](/consul/docs/api-gateway/upgrades) instructions for additional details. ## Supported Software @@ -52,7 +52,7 @@ description: >- - Kubernetes 1.24 is not supported at this time. - Kubectl 1.21+ - Envoy proxy support is determined by the Consul version deployed. Refer to - [Envoy Integration](/docs/connect/proxies/envoy) for details. + [Envoy Integration](/consul/docs/connect/proxies/envoy) for details. ## Kubernetes Gateway API Specification @@ -60,7 +60,7 @@ Supported version of the [Gateway API](https://gateway-api.sigs.k8s.io/) spec: v ## Upgrading -For detailed information on upgrading, please refer to the [Upgrades page](/docs/api-gateway/upgrades) +For detailed information on upgrading, please refer to the [Upgrades page](/consul/docs/api-gateway/upgrades) ## Known Issues The following issues are know to exist in the v0.4.0 release diff --git a/website/content/docs/release-notes/consul-api-gateway/v0_5_x.mdx b/website/content/docs/release-notes/consul-api-gateway/v0_5_x.mdx index 040433a8e3..c32b735bb6 100644 --- a/website/content/docs/release-notes/consul-api-gateway/v0_5_x.mdx +++ b/website/content/docs/release-notes/consul-api-gateway/v0_5_x.mdx @@ -13,7 +13,7 @@ We are pleased to announce the following updates to Consul API Gateway. - **Consul Dataplane Support:** Consul 1.14 introduces a simplified deployment architecture that eliminates the need to deploy node-level Consul clients on Kubernetes. This is referred to as Consul Dataplane. API Gateway 0.5.0 supports this type of deployment. -- **Routing to Services in Peered Clusters:** API Gateway now supports the ability to route traffic to services that are imported from peered Consul clusters. Cluster peering is was added in Consul 1.14. Refer to the `MeshService` [documentation](/docs/api-gateway/configuration/meshservice) for additional information. +- **Routing to Services in Peered Clusters:** API Gateway now supports the ability to route traffic to services that are imported from peered Consul clusters. Cluster peering is was added in Consul 1.14. Refer to the `MeshService` [documentation](/consul/docs/api-gateway/configuration/meshservice) for additional information. - **Deploy in Admin Partitions:** API Gateway can now be deployed in any Consul admin partition. Previous versions of API Gateway could only be deployed in the default partition. The partition is configured in the `GatewayClassConfig`. @@ -21,7 +21,7 @@ We are pleased to announce the following updates to Consul API Gateway. - **Distroless Envoy Containers:** API Gateway now uses the `envoy-distroless` container image of the Envoy proxy. This improves the security of a gateway by reducing the attack surface of Envoy. Consul Helm chart `1.0.0` or greater is required to use the distroless container image. -- **Support for Kubernetes Tolerations:** You can now configure toleration settings for the Consul API Gateway controller and Gateway instances made with the managed gateway class directly from the [Helm chart](/docs/k8s/helm#h-apigateway). Kubernetes toleration settings allow you to control which nodes in a K8s cluster that the API Gateway pods should be deployed on. Refer to [Taints and Tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) in the Kubernetes documentation for more information. +- **Support for Kubernetes Tolerations:** You can now configure toleration settings for the Consul API Gateway controller and Gateway instances made with the managed gateway class directly from the [Helm chart](/consul/docs/k8s/helm#h-apigateway). Kubernetes toleration settings allow you to control which nodes in a K8s cluster that the API Gateway pods should be deployed on. Refer to [Taints and Tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) in the Kubernetes documentation for more information. ## Supported software @@ -32,7 +32,7 @@ We are pleased to announce the following updates to Consul API Gateway. - Kubernetes 1.21+ - Kubernetes 1.25 is not supported at this time. - Kubectl 1.21+ -- Envoy proxy support is determined by the Consul version deployed. Refer to [Envoy Integration](/docs/connect/proxies/envoy) for details. +- Envoy proxy support is determined by the Consul version deployed. Refer to [Envoy Integration](/consul/docs/connect/proxies/envoy) for details. ## Kubernetes Gateway API specification @@ -40,7 +40,7 @@ Supported version of the [Gateway API](https://gateway-api.sigs.k8s.io/) spec: v ## Upgrading -For detailed information on upgrading, please refer to the [Upgrades page](/docs/api-gateway/upgrades) +For detailed information on upgrading, please refer to the [Upgrades page](/consul/docs/api-gateway/upgrades) ## Known issues At the time of release, there are no known issues in API Gateway v0.5.0 diff --git a/website/content/docs/release-notes/consul-ecs/v0_5_x.mdx b/website/content/docs/release-notes/consul-ecs/v0_5_x.mdx index 54b29b3b30..4aa6de68a1 100644 --- a/website/content/docs/release-notes/consul-ecs/v0_5_x.mdx +++ b/website/content/docs/release-notes/consul-ecs/v0_5_x.mdx @@ -9,11 +9,11 @@ description: >- ## Release Highlights -- **Audit Logging (Enterprise) :** Consul on ECS now captures authentication events and processes them with the HTTP API. Audit logging provides insight into access and usage patterns. Refer to [Audit Logging](/docs/ecs/enterprise#audit-logging) for usage information. +- **Audit Logging (Enterprise) :** Consul on ECS now captures authentication events and processes them with the HTTP API. Audit logging provides insight into access and usage patterns. Refer to [Audit Logging](/consul/docs/ecs/enterprise#audit-logging) for usage information. -- **AWS IAM Auth Method :** This feature provides support for Consul's AWS IAM auth method. This allows AWS IAM roles and users to authenticate with Consul to obtain ACL tokens. Refer to [ECS Configuration Reference](/docs/ecs/configuration-reference#consullogin) for configuration information. +- **AWS IAM Auth Method :** This feature provides support for Consul's AWS IAM auth method. This allows AWS IAM roles and users to authenticate with Consul to obtain ACL tokens. Refer to [ECS Configuration Reference](/consul/docs/ecs/configuration-reference#consullogin) for configuration information. -- **Mesh Gateways :** This feature introduces support for running mesh gateways as ECS tasks. Mesh gateways enable service mesh communication across datacenter and admin partition boundaries. Refer to [ECS Installation with Terraform](/docs/ecs/terraform/install#configure-the-gateway-task-module) for usage information. +- **Mesh Gateways :** This feature introduces support for running mesh gateways as ECS tasks. Mesh gateways enable service mesh communication across datacenter and admin partition boundaries. Refer to [ECS Installation with Terraform](/consul/docs/ecs/terraform/install#configure-the-gateway-task-module) for usage information. ## Supported Software Versions diff --git a/website/content/docs/release-notes/consul-k8s/v0_47_x.mdx b/website/content/docs/release-notes/consul-k8s/v0_47_x.mdx index b13d858fd7..3d266b1335 100644 --- a/website/content/docs/release-notes/consul-k8s/v0_47_x.mdx +++ b/website/content/docs/release-notes/consul-k8s/v0_47_x.mdx @@ -9,7 +9,7 @@ description: >- ## Release Highlights -- **Cluster Peering (Beta)**: This release introduces support for Cluster Peering, which allows service connectivity between two independent clusters. Enabling peering will deploy the peering controllers and PeeringAcceptor and PeeringDialer CRDs. The new CRDs are used to establish a peering connection between two clusters. Refer to [Cluster Peering on Kubernetes](/docs/connect/cluster-peering/k8s) for full instructions on using Cluster Peering on Kubernetes. +- **Cluster Peering (Beta)**: This release introduces support for Cluster Peering, which allows service connectivity between two independent clusters. Enabling peering will deploy the peering controllers and PeeringAcceptor and PeeringDialer CRDs. The new CRDs are used to establish a peering connection between two clusters. Refer to [Cluster Peering on Kubernetes](/consul/docs/connect/cluster-peering/k8s) for full instructions on using Cluster Peering on Kubernetes. - **Envoy Proxy Debugging CLI Commands**: This release introduces new commands to quickly identify proxies and troubleshoot Envoy proxies for sidecars and gateways. * Add `consul-k8s proxy list` command for displaying pods running Envoy managed by Consul. @@ -23,11 +23,11 @@ description: >- - Kubernetes 1.19-1.23 - Kubectl 1.19+ - Envoy proxy support is determined by the Consul version deployed. Refer to - [Envoy Integration](/docs/connect/proxies/envoy) for details. + [Envoy Integration](/consul/docs/connect/proxies/envoy) for details. ## Upgrading -For detailed information on upgrading, please refer to the [Upgrades page](/docs/k8s/upgrade) +For detailed information on upgrading, please refer to the [Upgrades page](/consul/docs/k8s/upgrade) ## Known Issues diff --git a/website/content/docs/release-notes/consul-k8s/v0_48_x.mdx b/website/content/docs/release-notes/consul-k8s/v0_48_x.mdx index 38c6732bf4..e3d26175a9 100644 --- a/website/content/docs/release-notes/consul-k8s/v0_48_x.mdx +++ b/website/content/docs/release-notes/consul-k8s/v0_48_x.mdx @@ -9,7 +9,7 @@ description: >- ## Release Highlights -- **Consul CNI Plugin**: This release introduces the Consul CNI Plugin for Consul on Kubernetes, to allow for configuring traffic redirection rules without escalated container privileges such as `CAP_NET_ADMIN`. Refer to [Enable the Consul CNI Plugin](/docs/k8s/installation/install#enable-the-consul-cni-plugin) for more details. The Consul CNI Plugin is supported for Consul K8s 0.48.0+ and Consul 1.13.1+. +- **Consul CNI Plugin**: This release introduces the Consul CNI Plugin for Consul on Kubernetes, to allow for configuring traffic redirection rules without escalated container privileges such as `CAP_NET_ADMIN`. Refer to [Enable the Consul CNI Plugin](/consul/docs/k8s/installation/install#enable-the-consul-cni-plugin) for more details. The Consul CNI Plugin is supported for Consul K8s 0.48.0+ and Consul 1.13.1+. - **Kubernetes 1.24 Support**: Add support for Kubernetes 1.24 where ServiceAccounts no longer have long-term JWT tokens. [[GH-1431](https://github.com/hashicorp/consul-k8s/pull/1431)] @@ -46,11 +46,11 @@ Example: - Kubernetes 1.19-1.24 - Kubectl 1.19+ - Envoy proxy support is determined by the Consul version deployed. Refer to - [Envoy Integration](/docs/connect/proxies/envoy) for details. + [Envoy Integration](/consul/docs/connect/proxies/envoy) for details. ## Upgrading -For detailed information on upgrading, please refer to the [Upgrades page](/docs/k8s/upgrade) +For detailed information on upgrading, please refer to the [Upgrades page](/consul/docs/k8s/upgrade) ## Known Issues The following issues are know to exist in the v0.48.0 release: diff --git a/website/content/docs/release-notes/consul-k8s/v0_49_x.mdx b/website/content/docs/release-notes/consul-k8s/v0_49_x.mdx index c7a3769138..57a66e5c3e 100644 --- a/website/content/docs/release-notes/consul-k8s/v0_49_x.mdx +++ b/website/content/docs/release-notes/consul-k8s/v0_49_x.mdx @@ -26,11 +26,11 @@ description: >- - Kubectl 1.19+ - Helm 3.2+ - Envoy proxy support is determined by the Consul version deployed. Refer to - [Envoy Integration](/docs/connect/proxies/envoy) for details. + [Envoy Integration](/consul/docs/connect/proxies/envoy) for details. ## Upgrading -For detailed information on upgrading, please refer to the [Upgrades page](/docs/k8s/upgrade) +For detailed information on upgrading, please refer to the [Upgrades page](/consul/docs/k8s/upgrade) ## Known Issues The following issues are know to exist in the v0.49.0 release: diff --git a/website/content/docs/release-notes/consul-k8s/v1_0_x.mdx b/website/content/docs/release-notes/consul-k8s/v1_0_x.mdx index 5edafb42fe..f34e2397c2 100644 --- a/website/content/docs/release-notes/consul-k8s/v1_0_x.mdx +++ b/website/content/docs/release-notes/consul-k8s/v1_0_x.mdx @@ -11,7 +11,7 @@ description: >- - **Simplified Service Mesh Deployments with Consul Dataplane:** Consul client agents are no longer deployed by default, and Consul service mesh no longer uses Consul clients to operate. A new component `consul-dataplane` is now injected as a sidecar-proxy instead of plain Envoy. `consul-dataplane` manages the Envoy proxy process and proxies xDS requests from Envoy to Consul servers. All service mesh consul-k8s components are configured to talk directly to Consul servers. -- **Cluster Peering GA with Peering over Mesh Gateways:** This version promotes Cluster Peering, a new model to federate Consul clusters for both service mesh and traditional service discovery, to General Availability. Cluster peering allows for service interconnectivity with looser coupling than the existing WAN federation. Cluster Peering on Consul K8s now enables [Cluster Peering with Control Plane traffic routed via Mesh Gateways](/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways) by default instead of provisioning load balancers using the `servers.exposeServers` stanza. In addtion, failover for service to service traffic over Cluster Peering can be configured through the `failover.targets` field in the [ServiceResolver](https://developer.hashicorp.com/consul/docs/connect/config-entries/service-resolver#targets) CRD. +- **Cluster Peering GA with Peering over Mesh Gateways:** This version promotes Cluster Peering, a new model to federate Consul clusters for both service mesh and traditional service discovery, to General Availability. Cluster peering allows for service interconnectivity with looser coupling than the existing WAN federation. Cluster Peering on Consul K8s now enables [Cluster Peering with Control Plane traffic routed via Mesh Gateways](/consul/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways) by default instead of provisioning load balancers using the `servers.exposeServers` stanza. In addtion, failover for service to service traffic over Cluster Peering can be configured through the `failover.targets` field in the [ServiceResolver](/consul/docs/connect/config-entries/service-resolver#targets) CRD. - **Consul API Gateway 0.5.0 Support:** Support to run Consul API Gateway without clients and allow Consul API Gateway to directly connect to Consul servers. @@ -19,7 +19,7 @@ description: >- - `client.enabled` now defaults to `false`. Setting it to true will deploy client agents, however, none of the consul-k8s components will use clients for their operation. For Vault on Kubernetes using Consul deployed on Kubernetes as a storage backend, `client.enabled` should be set to `true` prior to upgrading. - `externalServers.grpcPort` default is now 8502 instead of 8503. -- `sync-catalog` now communicates directly to Consul servers. When communicating to servers outside of Kubernetes, use the `externalServers.hosts` stanza as described in [Join External Servers to Consul on Kubernetes](/docs/k8s/deployment-configurations/servers-outside-kubernetes). +- `sync-catalog` now communicates directly to Consul servers. When communicating to servers outside of Kubernetes, use the `externalServers.hosts` stanza as described in [Join External Servers to Consul on Kubernetes](/consul/docs/k8s/deployment-configurations/servers-outside-kubernetes). - Consul snapshot agent runs as a sidecar to Consul servers. - `client.snapshotAgent` values are moved to `server.snapshotAgent`, with the exception of the following values: `client.snaphostAgent.replicas`, `client.snaphostAgent.serviceAccount` - `global.secretsBackend.vault.consulSnapshotAgentRole` value is now removed. You should now use the `global.secretsBackend.vault.consulServerRole` for access to any Vault secrets. @@ -39,14 +39,14 @@ description: >- ~> **Note:** Consul 1.13.x and 1.12.x is not supported. Please use Consul K8s 0.49.x if you want to use Consul 1.13.x or 1.12.x. - Consul 1.14.x. -- Consul Dataplane v1.0.x. Refer to [Envoy and Consul Dataplane](/docs/connect/proxies/envoy#envoy-and-consul-dataplane) for details about Consul Dataplane versions and the available packaged Envoy version. +- Consul Dataplane v1.0.x. Refer to [Envoy and Consul Dataplane](/consul/docs/connect/proxies/envoy#envoy-and-consul-dataplane) for details about Consul Dataplane versions and the available packaged Envoy version. - Kubernetes 1.22.x - 1.25.x - `kubectl` 1.22.x - 1.25.x - Helm 3.6+ ## Upgrading -For detailed information on upgrading, please refer to the [Upgrades page](/docs/k8s/upgrade) +For detailed information on upgrading, please refer to the [Upgrades page](/consul/docs/k8s/upgrade) ## Known Issues diff --git a/website/content/docs/release-notes/consul-terraform-sync/v0_6_x.mdx b/website/content/docs/release-notes/consul-terraform-sync/v0_6_x.mdx index 31fb9a8983..a4760fa7e4 100644 --- a/website/content/docs/release-notes/consul-terraform-sync/v0_6_x.mdx +++ b/website/content/docs/release-notes/consul-terraform-sync/v0_6_x.mdx @@ -14,7 +14,7 @@ We have implemented the following features in this release: ### Per-task Execution Mode with Support for Terraform Cloud Agent -You can now execute Terraform tasks in `remote` or `cloud agent` mode. For more information, refer to the [per-task execution mode documentation](/docs/nia/network-drivers/terraform-cloud#remote-workspaces). +You can now execute Terraform tasks in `remote` or `cloud agent` mode. For more information, refer to the [per-task execution mode documentation](/consul/docs/nia/network-drivers/terraform-cloud#remote-workspaces). ### HCP Consul Support @@ -22,15 +22,15 @@ CTS now supports interoperability with HCP Consul. CTS retrieves licenses from H ### Auto Service-registration with Consul and Health API Endpoint -CTS includes a new configuration block that automatically registers CTS as a service within Consul as soon as CTS is instantiated. This eliminates the manual step of registering CTS as a service within the Consul catalog. This service registration also enables health checking on CTS using the newly added [health API endpoint](/docs/nia/api/health#health). +CTS includes a new configuration block that automatically registers CTS as a service within Consul as soon as CTS is instantiated. This eliminates the manual step of registering CTS as a service within the Consul catalog. This service registration also enables health checking on CTS using the newly added [health API endpoint](/consul/docs/nia/api/health#health). ### CLI Discoverability -We improved CTS's CLI discoverability functionality. The `consul-terraform-sync` command features opt-in [autocompletion](/docs/nia/cli#autocompletion) for flags, subcommands, and arguments +We improved CTS's CLI discoverability functionality. The `consul-terraform-sync` command features opt-in [autocompletion](/consul/docs/nia/cli#autocompletion) for flags, subcommands, and arguments ### Health Check API -CTS includes a new [API endpoint](/docs/nia/api/health#health) that provides operators with the health status of their CTS instance. +CTS includes a new [API endpoint](/consul/docs/nia/api/health#health) that provides operators with the health status of their CTS instance. ## Supported Software Versions diff --git a/website/content/docs/release-notes/consul/v1_10_x.mdx b/website/content/docs/release-notes/consul/v1_10_x.mdx index 5b8f0c19b1..e4242ab757 100644 --- a/website/content/docs/release-notes/consul/v1_10_x.mdx +++ b/website/content/docs/release-notes/consul/v1_10_x.mdx @@ -9,7 +9,7 @@ description: >- ## Release Highlights -- **Transparent Proxy:** Simplifies deploying applications into the service mesh by using iptables to redirect traffic from applications running in virtual machines or Kubernetes through the Envoy proxy. [`consul connect redirect-traffic`](/commands/connect/redirect-traffic) now provides a CLI interface for applying traffic redirection `iptables` rules to redirect traffic through an inbound and outbound listener on the Envoy sidecar. More information on how to utilize Transparent Proxy for Consul on Kubernetes could be found on [Transparent Proxy](/docs/connect/transparent-proxy). +- **Transparent Proxy:** Simplifies deploying applications into the service mesh by using iptables to redirect traffic from applications running in virtual machines or Kubernetes through the Envoy proxy. [`consul connect redirect-traffic`](/consul/commands/connect/redirect-traffic) now provides a CLI interface for applying traffic redirection `iptables` rules to redirect traffic through an inbound and outbound listener on the Envoy sidecar. More information on how to utilize Transparent Proxy for Consul on Kubernetes could be found on [Transparent Proxy](/consul/docs/connect/transparent-proxy). - **Support for xDS v3 and Incremental xDS:** Consul 1.10 will default to using xDS version 3 and Incremental xDS for all supported Envoy proxy versions bootstrapped by the Consul 1.10 CLI. This is driven by the fact that xDS v2 was deprecated in Envoy 1.15 and disabled in Envoy 1.17. Envoy proxies bootstrapped with older Consul CLI binaries will continue to use the xDS v2 state-of-the-world API. @@ -26,7 +26,7 @@ description: >- ## Upgrading -For more detailed information, please refer to the [upgrade details page](/docs/upgrading/upgrade-specific#consul-1-10-0) and the changelogs. +For more detailed information, please refer to the [upgrade details page](/consul/docs/upgrading/upgrade-specific#consul-1-10-0) and the changelogs. ## Changelogs diff --git a/website/content/docs/release-notes/consul/v1_11_x.mdx b/website/content/docs/release-notes/consul/v1_11_x.mdx index 4b83f0506b..fb3c23d08c 100644 --- a/website/content/docs/release-notes/consul/v1_11_x.mdx +++ b/website/content/docs/release-notes/consul/v1_11_x.mdx @@ -9,27 +9,27 @@ description: >- ## Release Highlights -- **Admin Partitions (Enterprise)**: Consul 1.11.0 Enterprise introduces a new entity for defining administrative and networking boundaries within a Consul deployment. This feature also enables servers to communicate with clients over a specific gossip segment created for each partition. This release also enables cross partition communication between services across partitions, using Mesh Gateways. For more information refer to the [Admin Partitions](/docs/enterprise/admin-partitions) documentation. +- **Admin Partitions (Enterprise)**: Consul 1.11.0 Enterprise introduces a new entity for defining administrative and networking boundaries within a Consul deployment. This feature also enables servers to communicate with clients over a specific gossip segment created for each partition. This release also enables cross partition communication between services across partitions, using Mesh Gateways. For more information refer to the [Admin Partitions](/consul/docs/enterprise/admin-partitions) documentation. - **Virtual IPs for services deployed with Consul Service Mesh**: Consul will now generate a unique virtual IP for each service deployed within Consul Service Mesh, allowing transparent proxy to route to services within a data center that exist in different clusters or outside the service mesh. - **Replace [boltdb](https://github.com/boltdb/bolt) with [etcd-io/bbolt](https://github.com/etcd-io/bbolt) for raft log store**: Consul now leverages `etcd-io/bbolt` as the default implementation of `boltdb` instead of `boltdb/bolt`. This change also exposes a configuration to allow for disabling boltdb freelist syncing. In addition, Consul now emits metrics for the raft boltdb store to provide insights into boltdb performance. -- **TLS Certificates for Ingress Gateways via an SDS source**: Ingress Gateways can now be configured to retrieve TLS certificates from an external SDS Service and load the TLS certificates for Ingress listeners. This configuration is set using the `ingress-gateway` configuration entry via the [SDS](/docs/connect/config-entries/ingress-gateway#sds) stanza within the Ingress Gateway TLS configuration. +- **TLS Certificates for Ingress Gateways via an SDS source**: Ingress Gateways can now be configured to retrieve TLS certificates from an external SDS Service and load the TLS certificates for Ingress listeners. This configuration is set using the `ingress-gateway` configuration entry via the [SDS](/consul/docs/connect/config-entries/ingress-gateway#sds) stanza within the Ingress Gateway TLS configuration. -- **Vault Auth Method support for Connect CA Vault Provider**: Consul now supports configuring the Connect CA Vault provider to use auth methods for authentication to Vault. Consul supports using any non-deprecated auth method that is available in Vault v1.8.5, including AppRole, AliCloud, AWS, Azure, Cloud Foundry, GitHub, Google Cloud, JWT/OIDC, Kerberos, Kubernetes, LDAP, Oracle Cloud Infrastructure, Okta, Radius, TLS Certificates, and Username & Password. The Vault Auth Method for Connect CA Provider is utilized by default for the [Vault Secrets Backend](/docs/k8s/deployment-configurations/vault) feature on Consul on Kubernetes. Utilizing a Vault Auth method would no longer require a Vault token to be managed or provisioned ahead of time to be used for authentication to Vault. +- **Vault Auth Method support for Connect CA Vault Provider**: Consul now supports configuring the Connect CA Vault provider to use auth methods for authentication to Vault. Consul supports using any non-deprecated auth method that is available in Vault v1.8.5, including AppRole, AliCloud, AWS, Azure, Cloud Foundry, GitHub, Google Cloud, JWT/OIDC, Kerberos, Kubernetes, LDAP, Oracle Cloud Infrastructure, Okta, Radius, TLS Certificates, and Username & Password. The Vault Auth Method for Connect CA Provider is utilized by default for the [Vault Secrets Backend](/consul/docs/k8s/deployment-configurations/vault) feature on Consul on Kubernetes. Utilizing a Vault Auth method would no longer require a Vault token to be managed or provisioned ahead of time to be used for authentication to Vault. ## What's Changed - The legacy ACL system that was deprecated in Consul 1.4.0 has been removed. Before upgrading you should verify that all tokens and policies have been migrated to the newer ACL system. Complete the [Migrate Legacy ACL Tokens](https://learn.hashicorp.com/consul/day-2-agent-authentication/migrate-acl-tokens) tutorial to learn more. -- The `agent_master` ACL token has been renamed to `agent_recovery` ACL token. In addition, the `consul acl set-agent-token master` command has been replaced with `consul acl set-agent-token recovery`. See [ACL Agent Recovery Token](/docs/security/acl/acl-tokens#acl-agent-recovery-token) and [Consul ACL Set Agent Token](/commands/acl/set-agent-token) for more information. +- The `agent_master` ACL token has been renamed to `agent_recovery` ACL token. In addition, the `consul acl set-agent-token master` command has been replaced with `consul acl set-agent-token recovery`. See [ACL Agent Recovery Token](/consul/docs/security/acl/acl-tokens#acl-agent-recovery-token) and [Consul ACL Set Agent Token](/consul/commands/acl/set-agent-token) for more information. - Drops support for Envoy versions 1.15.x and 1.16.x ## Upgrading -For more detailed information, please refer to the [upgrade details page](/docs/upgrading/upgrade-specific#consul-1-11-0) and the changelogs. +For more detailed information, please refer to the [upgrade details page](/consul/docs/upgrading/upgrade-specific#consul-1-11-0) and the changelogs. ## Changelogs diff --git a/website/content/docs/release-notes/consul/v1_12_x.mdx b/website/content/docs/release-notes/consul/v1_12_x.mdx index dd354d60b4..2b11335b79 100644 --- a/website/content/docs/release-notes/consul/v1_12_x.mdx +++ b/website/content/docs/release-notes/consul/v1_12_x.mdx @@ -9,36 +9,36 @@ description: >- ## Release Highlights -- **AWS IAM Auth Method**: Consul now provides an AWS IAM auth method that allows AWS IAM roles and users to authenticate with Consul to obtain ACL tokens. Refer to [AWS IAM Auth Method](/docs/security/acl/auth-methods/aws-iam) for detailed configuration information. +- **AWS IAM Auth Method**: Consul now provides an AWS IAM auth method that allows AWS IAM roles and users to authenticate with Consul to obtain ACL tokens. Refer to [AWS IAM Auth Method](/consul/docs/security/acl/auth-methods/aws-iam) for detailed configuration information. -- **Per listener TLS Config**: It is now possible to configure TLS differently for each of Consul's listeners, such as HTTPS, gRPC, and the internal multiplexed RPC listener, using the `tls` stanza. Refer to [TLS Configuration Reference](/docs/agent/config/config-files#tls-configuration-reference) for more details. +- **Per listener TLS Config**: It is now possible to configure TLS differently for each of Consul's listeners, such as HTTPS, gRPC, and the internal multiplexed RPC listener, using the `tls` stanza. Refer to [TLS Configuration Reference](/consul/docs/agent/config/config-files#tls-configuration-reference) for more details. -- **AWS Lambda**: Adds the ability to invoke AWS Lambdas through terminating gateways, which allows for cross-datacenter communication, transparent proxy, and intentions with Consul Service Mesh. Refer to [AWS Lambda](/docs]/lambda) and [Invoke Lambda Functions](/docs/lambda/invocation) for more details. +- **AWS Lambda**: Adds the ability to invoke AWS Lambdas through terminating gateways, which allows for cross-datacenter communication, transparent proxy, and intentions with Consul Service Mesh. Refer to [AWS Lambda](/consul/docs]/lambda) and [Invoke Lambda Functions](/consul/docs/lambda/invocation) for more details. -- **Mesh-wide TLS min/max versions and cipher suites**: Using the [Mesh](/docs/connect/config-entries/mesh#tls) Config Entry or CRD, it is now possible to set TLS min/max versions and cipher suites for both inbound and outbound mTLS connections. +- **Mesh-wide TLS min/max versions and cipher suites**: Using the [Mesh](/consul/docs/connect/config-entries/mesh#tls) Config Entry or CRD, it is now possible to set TLS min/max versions and cipher suites for both inbound and outbound mTLS connections. - **Expanded details for ACL Permission Denied errors**: Details are now provided when a permission denied errors surface for RPC calls. Details include the accessor ID of the ACL token, the missing permission, and any namespace or partition that the error occurred on. -- **ACL token read**: The `consul acl token read -rules` command now includes an `-expanded` option to display detailed info about any policies and rules affecting the token. Refer to [Consul ACL Token read](/commands/acl/token/read) for more details. +- **ACL token read**: The `consul acl token read -rules` command now includes an `-expanded` option to display detailed info about any policies and rules affecting the token. Refer to [Consul ACL Token read](/consul/commands/acl/token/read) for more details. -- **Automatically reload agent config when watching agent config file changes**: When using the `auto-reload-config` CLI flag or `auto_reload_config` agent config option, Consul now automatically reloads the [reloadable configuration options](/docs/agent/config#reloadable-configuration) when configuration files change. Refer to [auto_reload_config](/docs/agent/config/cli-flags#_auto_reload_config) for more details. +- **Automatically reload agent config when watching agent config file changes**: When using the `auto-reload-config` CLI flag or `auto_reload_config` agent config option, Consul now automatically reloads the [reloadable configuration options](/consul/docs/agent/config#reloadable-configuration) when configuration files change. Refer to [auto_reload_config](/consul/docs/agent/config/cli-flags#_auto_reload_config) for more details. ## What's Changed -- Removes support for Envoy 1.17.x and Envoy 1.18.x, and adds support for Envoy 1.21.x and Envoy 1.22.x. Refer to the [Envoy Compatibility matrix](/docs/connect/proxies/envoy) for more details. +- Removes support for Envoy 1.17.x and Envoy 1.18.x, and adds support for Envoy 1.21.x and Envoy 1.22.x. Refer to the [Envoy Compatibility matrix](/consul/docs/connect/proxies/envoy) for more details. - The `disable_compat_1.9` option now defaults to true. Metrics formatted in the style of version 1.9, such as `consul.http...`, can still be enabled by setting disable_compat_1.9 = false. However, these metrics will be removed in 1.13. -- The `agent_master` ACL token has been renamed to `agent_recovery` ACL token. In addition, the `consul acl set-agent-token master` command has been replaced with `consul acl set-agent-token recovery`. Refer to [ACL Agent Recovery Token](/docs/security/acl/acl-tokens#acl-agent-recovery-token) and [Consul ACL Set Agent Token](/commands/acl/set-agent-token) for more information. +- The `agent_master` ACL token has been renamed to `agent_recovery` ACL token. In addition, the `consul acl set-agent-token master` command has been replaced with `consul acl set-agent-token recovery`. Refer to [ACL Agent Recovery Token](/consul/docs/security/acl/acl-tokens#acl-agent-recovery-token) and [Consul ACL Set Agent Token](/consul/commands/acl/set-agent-token) for more information. -- If TLS min versions and max versions are not specified, the TLS min/max versions default to the following values. For details on how to configure TLS min and max, refer to the [Mesh TLS config entry](/docs/connect/config-entries/mesh#tls) or CRD documentation. +- If TLS min versions and max versions are not specified, the TLS min/max versions default to the following values. For details on how to configure TLS min and max, refer to the [Mesh TLS config entry](/consul/docs/connect/config-entries/mesh#tls) or CRD documentation. - Incoming connections: TLS 1.2 for min0 version, TLS 1.3 for max version - Outgoing connections: TLS 1.2 for both TLS min and TLS max versions. ## Upgrading -For more detailed information, please refer to the [upgrade details page](/docs/upgrading/upgrade-specific#consul-1-12-0) and the changelogs. +For more detailed information, please refer to the [upgrade details page](/consul/docs/upgrading/upgrade-specific#consul-1-12-0) and the changelogs. ## Changelogs diff --git a/website/content/docs/release-notes/consul/v1_13_x.mdx b/website/content/docs/release-notes/consul/v1_13_x.mdx index 03a08c57be..b760b3f6b2 100644 --- a/website/content/docs/release-notes/consul/v1_13_x.mdx +++ b/website/content/docs/release-notes/consul/v1_13_x.mdx @@ -9,29 +9,29 @@ description: >- ## Release Highlights -- **Cluster Peering (Beta)**: This version adds a new model to federate Consul clusters for both service mesh and traditional service discovery. Cluster peering allows for service interconnectivity with looser coupling than the existing WAN federation. For more information, refer to the [cluster peering](/docs/connect/cluster-peering) documentation. +- **Cluster Peering (Beta)**: This version adds a new model to federate Consul clusters for both service mesh and traditional service discovery. Cluster peering allows for service interconnectivity with looser coupling than the existing WAN federation. For more information, refer to the [cluster peering](/consul/docs/connect/cluster-peering) documentation. -- **Transparent proxying through terminating gateways**: This version adds egress traffic control to destinations outside of Consul's catalog, such as APIs on the public internet. Transparent proxies can dial [destinations defined in service-defaults](/docs/connect/config-entries/service-defaults#destination) and have the traffic routed through terminating gateways. For more information, refer to the [terminating gateway](/docs/connect/gateways/terminating-gateway#terminating-gateway-configuration) documentation. +- **Transparent proxying through terminating gateways**: This version adds egress traffic control to destinations outside of Consul's catalog, such as APIs on the public internet. Transparent proxies can dial [destinations defined in service-defaults](/consul/docs/connect/config-entries/service-defaults#destination) and have the traffic routed through terminating gateways. For more information, refer to the [terminating gateway](/consul/docs/connect/gateways/terminating-gateway#terminating-gateway-configuration) documentation. - **Enables TLS on the Envoy Prometheus endpoint**: The Envoy prometheus endpoint can be enabled when `envoy_prometheus_bind_addr` is set and then secured over TLS using new CLI flags for the `consul connect envoy` command. These commands are: `-prometheus-ca-file`, `-prometheus-ca-path`, `-prometheus-cert-file` and `-prometheus-key-file`. The CA, cert, and key can be provided to Envoy by a Kubernetes mounted volume so that Envoy can watch the files and dynamically reload the certs when the volume is updated. -- **UDP Health Checks**: Adds the ability to register service discovery health checks that periodically send UDP datagrams to the specified IP/hostname and port. Refer to [UDP checks](/docs/discovery/checks#udp-interval). +- **UDP Health Checks**: Adds the ability to register service discovery health checks that periodically send UDP datagrams to the specified IP/hostname and port. Refer to [UDP checks](/consul/docs/discovery/checks#udp-interval). ## What's Changed -- Removes support for Envoy 1.19.x and adds support for Envoy 1.23. Refer to the [Envoy Compatibility matrix](/docs/connect/proxies/envoy) for more details. +- Removes support for Envoy 1.19.x and adds support for Envoy 1.23. Refer to the [Envoy Compatibility matrix](/consul/docs/connect/proxies/envoy) for more details. -- The [`disable_compat_19`](/docs/agent/config/config-files#telemetry-disable_compat_1.9) telemetry configuration option is now removed. In Consul versions 1.10.x through 1.11.x, the config defaulted to `false`. In version 1.12.x it defaulted to `true`. Before upgrading you should remove this flag from your config if the flag is being used. +- The [`disable_compat_19`](/consul/docs/agent/config/config-files#telemetry-disable_compat_1.9) telemetry configuration option is now removed. In Consul versions 1.10.x through 1.11.x, the config defaulted to `false`. In version 1.12.x it defaulted to `true`. Before upgrading you should remove this flag from your config if the flag is being used. ## Upgrading -For more detailed information, please refer to the [upgrade details page](/docs/upgrading/upgrade-specific#consul-1-13-0) and the changelogs. +For more detailed information, please refer to the [upgrade details page](/consul/docs/upgrading/upgrade-specific#consul-1-13-0) and the changelogs. ## Known Issues The following issues are know to exist in the 1.13.0 release: - Consul 1.13.1 fixes a compatibility issue when restoring snapshots from pre-1.13.0 versions of Consul. Refer to GitHub issue [[GH-14149](https://github.com/hashicorp/consul/issues/14149)] for more details. -- Consul 1.13.0 and Consul 1.13.1 default to requiring TLS for gRPC communication with Envoy proxies when auto-encrypt and auto-config are enabled. In environments where Envoy proxies are not already configured to use TLS for gRPC, upgrading Consul 1.13 will cause Envoy proxies to disconnect from the control plane (Consul agents). A future patch release will default to disabling TLS by default for GRPC communication with Envoy proxies when using Service Mesh and auto-config or auto-encrypt. Refer to GitHub issue [[GH-14253](https://github.com/hashicorp/consul/issues/14253)] and [Service Mesh deployments using auto-config and auto-encrypt](https://www.consul.io/docs/upgrading/upgrade-specific#service-mesh-deployments-using-auto-encrypt-or-auto-config) for more details. +- Consul 1.13.0 and Consul 1.13.1 default to requiring TLS for gRPC communication with Envoy proxies when auto-encrypt and auto-config are enabled. In environments where Envoy proxies are not already configured to use TLS for gRPC, upgrading Consul 1.13 will cause Envoy proxies to disconnect from the control plane (Consul agents). A future patch release will default to disabling TLS by default for GRPC communication with Envoy proxies when using Service Mesh and auto-config or auto-encrypt. Refer to GitHub issue [[GH-14253](https://github.com/hashicorp/consul/issues/14253)] and [Service Mesh deployments using auto-config and auto-encrypt](/consul/docs/upgrading/upgrade-specific#service-mesh-deployments-using-auto-encrypt-or-auto-config) for more details. ## Changelogs diff --git a/website/content/docs/release-notes/consul/v1_14_x.mdx b/website/content/docs/release-notes/consul/v1_14_x.mdx index b907116d9b..d6b5fa5ad8 100644 --- a/website/content/docs/release-notes/consul/v1_14_x.mdx +++ b/website/content/docs/release-notes/consul/v1_14_x.mdx @@ -9,13 +9,13 @@ description: >- ## Release Highlights -- **Cluster Peering (GA):** This version promotes Cluster Peering, a new model to federate Consul clusters for both service mesh and traditional service discovery, to General Availability. Cluster peering allows for service interconnectivity with looser coupling than the existing WAN federation. For more information, refer to the [cluster peering](/docs/connect/cluster-peering) documentation. Some notable improvements to Cluster Peering include: +- **Cluster Peering (GA):** This version promotes Cluster Peering, a new model to federate Consul clusters for both service mesh and traditional service discovery, to General Availability. Cluster peering allows for service interconnectivity with looser coupling than the existing WAN federation. For more information, refer to the [cluster peering](/consul/docs/connect/cluster-peering) documentation. Some notable improvements to Cluster Peering include: - - **Cluster Peering Failover:** Cluster Peering now supports the ability to redirect to services running on cluster peers with service resolvers. More details for configuring failover across peers is provided in the Service Resolver [failover](/docs/connect/config-entries/service-resolver#failover) stanza. + - **Cluster Peering Failover:** Cluster Peering now supports the ability to redirect to services running on cluster peers with service resolvers. More details for configuring failover across peers is provided in the Service Resolver [failover](/consul/docs/connect/config-entries/service-resolver#failover) stanza. - - **Control Plane traffic over Mesh Gateways:** Cluster Peering now supports the establishing peering through Mesh Gateways. More detail on using Mesh Gateways for Cluster Peering are found in [Enabling Peering Control Plane Traffic](/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways). Mesh Gateways are used by default for [Cluster Peering on Kubernetes](/docs/connect/cluster-peering/k8s). + - **Control Plane traffic over Mesh Gateways:** Cluster Peering now supports the establishing peering through Mesh Gateways. More detail on using Mesh Gateways for Cluster Peering are found in [Enabling Peering Control Plane Traffic](/consul/docs/connect/gateways/mesh-gateway/peering-via-mesh-gateways). Mesh Gateways are used by default for [Cluster Peering on Kubernetes](/consul/docs/connect/cluster-peering/k8s). -- **Simplified Service Mesh with Consul Dataplane:** Support for a new `consul-dataplane`, a lightweight process for managing Envoy proxies introduced in Consul v1.14.0. Consul Dataplane removes the need to run client agents on every node in a cluster for service discovery and service mesh. Instead, Consul deploys sidecar proxies that provide lower latency, support additional runtimes, and integrate with cloud infrastructure providers. Read more in [Simplified Service Mesh with Consul Dataplane](/docs/connect/dataplane). +- **Simplified Service Mesh with Consul Dataplane:** Support for a new `consul-dataplane`, a lightweight process for managing Envoy proxies introduced in Consul v1.14.0. Consul Dataplane removes the need to run client agents on every node in a cluster for service discovery and service mesh. Instead, Consul deploys sidecar proxies that provide lower latency, support additional runtimes, and integrate with cloud infrastructure providers. Read more in [Simplified Service Mesh with Consul Dataplane](/consul/docs/connect/dataplane). ~> **Note:** Currently `consul-dataplane` is only supported on clusters running on Consul on Kubernetes 1.0+. @@ -32,7 +32,7 @@ changes the names of some [Envoy dynamic HTTP metrics](https://www.envoyproxy.io ## Upgrading -For more detailed information, please refer to the [upgrade details page](/docs/upgrading/upgrade-specific#consul-1-14-0) and the changelogs. +For more detailed information, please refer to the [upgrade details page](/consul/docs/upgrading/upgrade-specific#consul-1-14-0) and the changelogs. ## Known Issues diff --git a/website/content/docs/release-notes/consul/v1_9_x.mdx b/website/content/docs/release-notes/consul/v1_9_x.mdx index dfc0bd0417..8caa90c89f 100644 --- a/website/content/docs/release-notes/consul/v1_9_x.mdx +++ b/website/content/docs/release-notes/consul/v1_9_x.mdx @@ -23,7 +23,7 @@ description: >- - **Active Health Checks for Consul on Kubernetes:** Consul service mesh now integrates with Kubernetes Readiness probes. This provides the ability to natively detect health status from Kubernetes via Readiness probe, and is then used for directing service mesh traffic. - **Streaming:** This feature introduces a major architectural enhancement in how update notifications for blocking queries are delivered within the cluster. Streaming results in very significant reduction of CPU and network bandwidth usage on Consul servers in large-scale deployments. Streaming is particularly helpful in scaling blocking queries in Consul clusters that have rapid changes in service state. - - Streaming is now available for the service health HTTP endpoint, and can be enabled through the [`use_streaming_backend`](/docs/agent/config/config-files#use_streaming_backend) client configuration option, and [`rpc.enable_streaming`](/docs/agent/config/config-files#rpc_enable_streaming) option on the servers. We will continue to enable streaming in more endpoints in subsequent releases. + - Streaming is now available for the service health HTTP endpoint, and can be enabled through the [`use_streaming_backend`](/consul/docs/agent/config/config-files#use_streaming_backend) client configuration option, and [`rpc.enable_streaming`](/consul/docs/agent/config/config-files#rpc_enable_streaming) option on the servers. We will continue to enable streaming in more endpoints in subsequent releases. ## What's Changed diff --git a/website/content/docs/security/acl/acl-federated-datacenters.mdx b/website/content/docs/security/acl/acl-federated-datacenters.mdx index dae636025c..390b5c7571 100644 --- a/website/content/docs/security/acl/acl-federated-datacenters.mdx +++ b/website/content/docs/security/acl/acl-federated-datacenters.mdx @@ -17,11 +17,11 @@ Consul versions 1.4.0 and later ## Configure ACLs in the Primary Datacenter -In a [federated Consul deployment](/docs/k8s/deployment-configurations/multi-cluster), one of the datacenters is marked as the primary datacenter. +In a [federated Consul deployment](/consul/docs/k8s/deployment-configurations/multi-cluster), one of the datacenters is marked as the primary datacenter. The `acl` configuration block should be added to the primary datacenter server's configuration file as shown in the following example. -See the [ACL Config Stanza](/docs/agent/config/config-files#acl) for more detailed descriptions of each option. +See the [ACL Config Stanza](/consul/docs/agent/config/config-files#acl) for more detailed descriptions of each option. -> **Versions before 1.11.0:** The `initial_management` token was called the `master` token in versions prior to 1.11.0 @@ -67,10 +67,10 @@ acl = { ~> **Warning:** Note that most enterprise deployments have security requirements that prevent specifying tokens in configuration files. The `enable_token_persistence` flag is also set in the configuration example so that the token is stored to disk in the agent's -[data directory](/docs/agent/config/config-files#_data_dir). Any future changes to the token that are made through the [API](/api-docs/agent#update-acl-tokens) will +[data directory](/consul/docs/agent/config/config-files#_data_dir). Any future changes to the token that are made through the [API](/consul/api-docs/agent#update-acl-tokens) will be persisted to the same location, and the value in the config file will be ignored. -The ACL agent token can also be set using the [`consul acl set-agent-token`](/commands/acl/set-agent-token) CLI as shown below. +The ACL agent token can also be set using the [`consul acl set-agent-token`](/consul/commands/acl/set-agent-token) CLI as shown below. ```shell-session $ consul acl set-agent-token agent "" @@ -85,7 +85,7 @@ provided to them. ### Create the replication token for ACL Management Replication tokens are needed for ACL token replication and -to create both [configuration entries](/docs/agent/config-entries) and [auth methods](/docs/security/acl/auth-methods) +to create both [configuration entries](/consul/docs/agent/config-entries) and [auth methods](/consul/docs/security/acl/auth-methods) in connected secondary datacenters. Replication tokens require the following permissions: @@ -163,8 +163,8 @@ global tokens already present in the secondary datacenter will be lost. For production environments, consider configuring ACL replication in your initial datacenter bootstrapping process. -~> **Warning:** If you are using [Consul Enterprise](/docs/enterprise) and -the [Admin Partitions](/docs/enterprise/admin-partitions) +~> **Warning:** If you are using [Consul Enterprise](/consul/docs/enterprise) and +the [Admin Partitions](/consul/docs/enterprise/admin-partitions) feature, only ACL tokens in the default partition are replicated to other datacenters. ## WAN Join Servers @@ -180,12 +180,12 @@ $ consul join -token="ACL_MANAGEMENT_TOKEN" -wan [server 1, server 2, ...] ## Configure Clients in Secondary Datacenters -When ACLs are enabled, client agents need a special token known as the [`agent token`](/docs/security/acl/acl-tokens#acl-agent-token) to perform internal operations. Agent tokens need to have the right policies for node related actions, including -registering itself in the catalog, updating node level health checks, and performing [anti-entropy](/docs/architecture/anti-entropy) syncing. +When ACLs are enabled, client agents need a special token known as the [`agent token`](/consul/docs/security/acl/acl-tokens#acl-agent-token) to perform internal operations. Agent tokens need to have the right policies for node related actions, including +registering itself in the catalog, updating node level health checks, and performing [anti-entropy](/consul/docs/architecture/anti-entropy) syncing. ### Generate Agent ACL Token -[ACL Node Identities](/docs/security/acl#node-identities) were introduced +[ACL Node Identities](/consul/docs/security/acl#node-identities) were introduced in Consul 1.8.1 and enable easily creating agent tokens with appropriately scoped policies. To generate the ACL token using node identity, run the following command: @@ -234,5 +234,5 @@ Note that client agents have to be restarted for ACL related configuration chang ## Summary After completing the above steps, a federated Consul cluster can be used with ACLs. Refer to -[ACL Replication Guide](https://learn.hashicorp.com/tutorials/consul/access-control-replication-multiple-datacenters?in=consul/security-operations) +[ACL Replication Guide](/consul/tutorials/security-operations/access-control-replication-multiple-datacenters) for more on this topic. diff --git a/website/content/docs/security/acl/acl-legacy.mdx b/website/content/docs/security/acl/acl-legacy.mdx index 6480e62177..c524f348ea 100644 --- a/website/content/docs/security/acl/acl-legacy.mdx +++ b/website/content/docs/security/acl/acl-legacy.mdx @@ -7,24 +7,24 @@ description: >- # ACL System in Legacy Mode --> **1.3.0 and earlier:** This document only applies in Consul versions 1.3.0 and before. If you are using version 1.4.0 or later please use the updated documentation [here](/docs/security/acl). +-> **1.3.0 and earlier:** This document only applies in Consul versions 1.3.0 and before. If you are using version 1.4.0 or later please use the updated documentation [here](/consul/docs/security/acl). ~> **Alert: Deprecation Notice** The ACL system described here was Consul's original ACL implementation. The legacy ACL system was deprecated in Consul 1.4.0 and removed in Consul 1.11.0. -The documentation for the new ACL system can be found [here](/docs/security/acl). For information on how to migrate to the new ACL System, please read the [Migrate Legacy ACL Tokens](https://learn.hashicorp.com/consul/day-2-agent-authentication/migrate-acl-tokens) tutorial. +The documentation for the new ACL system can be found [here](/consul/docs/security/acl). For information on how to migrate to the new ACL System, please read the [Migrate Legacy ACL Tokens](https://learn.hashicorp.com/consul/day-2-agent-authentication/migrate-acl-tokens) tutorial. The legacy documentation has two sections. - The [New ACL System Differences](#new-acl-system-differences) section - details the differences between ACLs in Consul 1.4.0 and older versions. You should read this section before upgrading to Consul 1.4.0 and [migrating](/docs/security/acl/acl-migrate-tokens) tokens. + details the differences between ACLs in Consul 1.4.0 and older versions. You should read this section before upgrading to Consul 1.4.0 and [migrating](/consul/docs/security/acl/acl-migrate-tokens) tokens. - The [Legacy ACL System documentation](#legacy-acl-system) section details the ACL system in Consul 1.3.0 and older. # New ACL System Differences -The [ACL System documentation](/docs/security/acl) and [legacy ACL -documentation](/docs/security/acl/acl-legacy) describes the new and old systems in +The [ACL System documentation](/consul/docs/security/acl) and [legacy ACL +documentation](/consul/docs/security/acl/acl-legacy) describes the new and old systems in detail. Below is a summary of the changes that need to be considered when migrating legacy tokens to the new system. @@ -69,24 +69,24 @@ key_prefix "foo" { policy = "write" } The "old" API endpoints below continue to work for backwards compatibility but will continue to create or show only "legacy" tokens that can't take full advantage of the new ACL system improvements. They are documented fully under -[Legacy Tokens](/api-docs/acl/legacy). +[Legacy Tokens](/consul/api-docs/acl/legacy). -- [`PUT /acl/create` - Create Legacy Token](/api-docs/acl/legacy#create-acl-token) -- [`PUT /acl/update` - Update Legacy Token](/api-docs/acl/legacy#update-acl-token) -- [`PUT /acl/destroy/:uuid` - Delete Legacy Token](/api-docs/acl/legacy#delete-acl-token) -- [`GET /acl/info/:uuid` - Read Legacy Token](/api-docs/acl/legacy#read-acl-token) -- [`PUT /acl/clone/:uuid` - Clone Legacy Token](/api-docs/acl/legacy#clone-acl-token) -- [`GET /acl/list` - List Legacy Tokens](/api-docs/acl/legacy#list-acls) +- [`PUT /acl/create` - Create Legacy Token](/consul/api-docs/acl/legacy#create-acl-token) +- [`PUT /acl/update` - Update Legacy Token](/consul/api-docs/acl/legacy#update-acl-token) +- [`PUT /acl/destroy/:uuid` - Delete Legacy Token](/consul/api-docs/acl/legacy#delete-acl-token) +- [`GET /acl/info/:uuid` - Read Legacy Token](/consul/api-docs/acl/legacy#read-acl-token) +- [`PUT /acl/clone/:uuid` - Clone Legacy Token](/consul/api-docs/acl/legacy#clone-acl-token) +- [`GET /acl/list` - List Legacy Tokens](/consul/api-docs/acl/legacy#list-acls) The new ACL system includes new API endpoints to manage -the [ACL System](/api-docs/acl), [Tokens](/api-docs/acl/tokens) -and [Policies](/api-docs/acl/policies). +the [ACL System](/consul/api-docs/acl), [Tokens](/consul/api-docs/acl/tokens) +and [Policies](/consul/api-docs/acl/policies). # Legacy ACL System ~> **Warning**: In this document we use the deprecated configuration parameter `acl_datacenter`. In Consul 1.4 and newer the -parameter has been updated to [`primary_datacenter`](/docs/agent/config/config-files#primary_datacenter). +parameter has been updated to [`primary_datacenter`](/consul/docs/agent/config/config-files#primary_datacenter). Consul provides an optional Access Control List (ACL) system which can be used to control access to data and APIs. The ACL is @@ -102,8 +102,8 @@ all while providing administrative insight. #### ACL Tokens The ACL system is based on tokens, which are managed by Consul operators via Consul's -[ACL API](/api-docs/acl), or systems like -[HashiCorp's Vault](https://www.vaultproject.io/docs/secrets/consul). +[ACL API](/consul/api-docs/acl), or systems like +[HashiCorp's Vault](/vault/docs/secrets/consul). Every token has an ID, name, type, and rule set. The ID is a randomly generated UUID, making it infeasible to guess. The name is opaque to Consul and human readable. @@ -111,22 +111,22 @@ The type is either "client" (meaning the token cannot modify ACL rules) or "mana (meaning the token is allowed to perform all actions). The token ID is passed along with each RPC request to the servers. Consul's -[HTTP endpoints](/api-docs) can accept tokens via the `token` +[HTTP endpoints](/consul/api-docs) can accept tokens via the `token` query string parameter, or the `X-Consul-Token` request header, or Authorization Bearer token [RFC6750](https://tools.ietf.org/html/rfc6750). Consul's -[CLI commands](/commands) can accept tokens via the +[CLI commands](/consul/commands) can accept tokens via the `token` argument, or the `CONSUL_HTTP_TOKEN` environment variable. If no token is provided, the rules associated with a special, configurable anonymous token are automatically applied. The anonymous token is managed using the -[ACL API](/api-docs/acl) like any other ACL token, but using `anonymous` for the ID. +[ACL API](/consul/api-docs/acl) like any other ACL token, but using `anonymous` for the ID. #### ACL Rules and Scope Tokens are bound to a set of rules that control which Consul resources the token has access to. Policies can be defined in either an allowlist or denylist mode depending on the configuration of -[`acl_default_policy`](/docs/agent/config/config-files#acl_default_policy). If the default +[`acl_default_policy`](/consul/docs/agent/config/config-files#acl_default_policy). If the default policy is to "deny" all actions, then token rules can be set to allowlist specific actions. In the inverse, the "allow" all default behavior is a denylist where rules are used to prohibit actions. By default, Consul will allow all actions. @@ -136,28 +136,28 @@ rules: | Policy | Scope | | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`agent`](#agent-rules) | Utility operations in the [Agent API](/api-docs/agent), other than service and check registration | -| [`event`](#event-rules) | Listing and firing events in the [Event API](/api-docs/event) | -| [`key`](#key-value-rules) | Key/value store operations in the [KV Store API](/api-docs/kv) | -| [`keyring`](#keyring-rules) | Keyring operations in the [Keyring API](/api-docs/operator/keyring) | -| [`node`](#node-rules) | Node-level catalog operations in the [Catalog API](/api-docs/catalog), [Health API](/api-docs/health), [Prepared Query API](/api-docs/query), [Network Coordinate API](/api-docs/coordinate), and [Agent API](/api-docs/agent) | -| [`operator`](#operator-rules) | Cluster-level operations in the [Operator API](/api-docs/operator), other than the [Keyring API](/api-docs/operator/keyring) | -| [`query`](#prepared-query-rules) | Prepared query operations in the [Prepared Query API](/api-docs/query) | -| [`service`](#service-rules) | Service-level catalog operations in the [Catalog API](/api-docs/catalog), [Health API](/api-docs/health), [Prepared Query API](/api-docs/query), and [Agent API](/api-docs/agent) | -| [`session`](#session-rules) | Session operations in the [Session API](/api-docs/session) | +| [`agent`](#agent-rules) | Utility operations in the [Agent API](/consul/api-docs/agent), other than service and check registration | +| [`event`](#event-rules) | Listing and firing events in the [Event API](/consul/api-docs/event) | +| [`key`](#key-value-rules) | Key/value store operations in the [KV Store API](/consul/api-docs/kv) | +| [`keyring`](#keyring-rules) | Keyring operations in the [Keyring API](/consul/api-docs/operator/keyring) | +| [`node`](#node-rules) | Node-level catalog operations in the [Catalog API](/consul/api-docs/catalog), [Health API](/consul/api-docs/health), [Prepared Query API](/consul/api-docs/query), [Network Coordinate API](/consul/api-docs/coordinate), and [Agent API](/consul/api-docs/agent) | +| [`operator`](#operator-rules) | Cluster-level operations in the [Operator API](/consul/api-docs/operator), other than the [Keyring API](/consul/api-docs/operator/keyring) | +| [`query`](#prepared-query-rules) | Prepared query operations in the [Prepared Query API](/consul/api-docs/query) | +| [`service`](#service-rules) | Service-level catalog operations in the [Catalog API](/consul/api-docs/catalog), [Health API](/consul/api-docs/health), [Prepared Query API](/consul/api-docs/query), and [Agent API](/consul/api-docs/agent) | +| [`session`](#session-rules) | Session operations in the [Session API](/consul/api-docs/session) | Since Consul snapshots actually contain ACL tokens, the -[Snapshot API](/api-docs/snapshot) requires a management token for snapshot operations +[Snapshot API](/consul/api-docs/snapshot) requires a management token for snapshot operations and does not use a special policy. The following resources are not covered by ACL policies: -1. The [Status API](/api-docs/status) is used by servers when bootstrapping and exposes +1. The [Status API](/consul/api-docs/status) is used by servers when bootstrapping and exposes basic IP and port information about the servers, and does not allow modification of any state. 2. The datacenter listing operation of the - [Catalog API](/api-docs/catalog#list-datacenters) similarly exposes the names of known + [Catalog API](/consul/api-docs/catalog#list-datacenters) similarly exposes the names of known Consul datacenters, and does not allow modification of any state. Constructing rules from these policies is covered in detail in the @@ -166,9 +166,9 @@ Constructing rules from these policies is covered in detail in the #### ACL Datacenter All nodes (clients and servers) must be configured with a -[`acl_datacenter`](/docs/agent/config/config-files#acl_datacenter) which enables ACL +[`acl_datacenter`](/consul/docs/agent/config/config-files#acl_datacenter) which enables ACL enforcement but also specifies the authoritative datacenter. Consul relies on -[RPC forwarding](/docs/architecture) to support multi-datacenter +[RPC forwarding](/consul/docs/architecture) to support multi-datacenter configurations. However, because requests can be made across datacenter boundaries, ACL tokens must be valid globally. To avoid consistency issues, a single datacenter is considered authoritative and stores the canonical set of tokens. @@ -176,14 +176,14 @@ is considered authoritative and stores the canonical set of tokens. When a request is made to an agent in a non-authoritative datacenter, it must be resolved into the appropriate policy. This is done by reading the token from the authoritative server and caching the result for a configurable -[`acl_ttl`](/docs/agent/config/config-files#acl_ttl). The implication of caching is that +[`acl_ttl`](/consul/docs/agent/config/config-files#acl_ttl). The implication of caching is that the cache TTL is an upper bound on the staleness of policy that is enforced. It is possible to set a zero TTL, but this has adverse performance impacts, as every request requires refreshing the policy via an RPC call. During an outage of the ACL datacenter, or loss of connectivity, the cache will be used as long as the TTL is valid, or the cache may be extended if the -[`acl_down_policy`](/docs/agent/config/config-files#acl_down_policy) is set accordingly. +[`acl_down_policy`](/consul/docs/agent/config/config-files#acl_down_policy) is set accordingly. This configuration also allows the ACL system to fail open or closed. [ACL replication](#replication) is also available to allow for the full set of ACL tokens to be replicated for use during an outage. @@ -195,10 +195,10 @@ as to whether they are set on servers, clients, or both. | Configuration Option | Servers | Clients | Purpose | | --------------------------------------------------------------------- | ---------- | ---------- | ----------------------------------------------------------------------------------------- | -| [`acl_datacenter`](/docs/agent/config/config-files#acl_datacenter) | `REQUIRED` | `REQUIRED` | Master control that enables ACLs by defining the authoritative Consul datacenter for ACLs | -| [`acl_default_policy`](/docs/agent/config/config-files#acl_default_policy_legacy) | `OPTIONAL` | `N/A` | Determines allowlist or denylist mode | -| [`acl_down_policy`](/docs/agent/config/config-files#acl_down_policy_legacy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the ACL datacenter is offline | -| [`acl_ttl`](/docs/agent/config/config-files#acl_ttl_legacy) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACLs | +| [`acl_datacenter`](/consul/docs/agent/config/config-files#acl_datacenter) | `REQUIRED` | `REQUIRED` | Master control that enables ACLs by defining the authoritative Consul datacenter for ACLs | +| [`acl_default_policy`](/consul/docs/agent/config/config-files#acl_default_policy_legacy) | `OPTIONAL` | `N/A` | Determines allowlist or denylist mode | +| [`acl_down_policy`](/consul/docs/agent/config/config-files#acl_down_policy_legacy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the ACL datacenter is offline | +| [`acl_ttl`](/consul/docs/agent/config/config-files#acl_ttl_legacy) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACLs | There are some additional configuration items related to [ACL replication](#replication) and [Version 8 ACL support](#version_8_acls). These are discussed in those respective sections @@ -209,17 +209,17 @@ system, or accessing Consul in special situations: | Special Token | Servers | Clients | Purpose | | ------------------------------------------------------------------------------------------| ---------- | ---------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`acl_agent_master_token`](/docs/agent/config/config-files#acl_agent_master_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that can be used to access [Agent API](/api-docs/agent) when the ACL datacenter isn't available, or servers are offline (for clients); used for setting up the cluster such as doing initial join operations, see the [ACL Agent Master Token](#acl-agent-master-token) section for more details | -| [`acl_agent_token`](/docs/agent/config/config-files#acl_agent_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that is used for an agent's internal operations, see the [ACL Agent Token](#acl-agent-token) section for more details | -| [`acl_master_token`](/docs/agent/config/config-files#acl_master_token_legacy) | `REQUIRED` | `N/A` | Special token used to bootstrap the ACL system, see the [Bootstrapping ACLs](#bootstrapping-acls) section for more details | -| [`acl_token`](/docs/agent/config/config-files#acl_token_legacy) | `OPTIONAL` | `OPTIONAL` | Default token to use for client requests where no token is supplied; this is often configured with read-only access to services to enable DNS service discovery on agents | +| [`acl_agent_master_token`](/consul/docs/agent/config/config-files#acl_agent_master_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that can be used to access [Agent API](/consul/api-docs/agent) when the ACL datacenter isn't available, or servers are offline (for clients); used for setting up the cluster such as doing initial join operations, see the [ACL Agent Master Token](#acl-agent-master-token) section for more details | +| [`acl_agent_token`](/consul/docs/agent/config/config-files#acl_agent_token_legacy) | `OPTIONAL` | `OPTIONAL` | Special token that is used for an agent's internal operations, see the [ACL Agent Token](#acl-agent-token) section for more details | +| [`acl_master_token`](/consul/docs/agent/config/config-files#acl_master_token_legacy) | `REQUIRED` | `N/A` | Special token used to bootstrap the ACL system, see the [Bootstrapping ACLs](#bootstrapping-acls) section for more details | +| [`acl_token`](/consul/docs/agent/config/config-files#acl_token_legacy) | `OPTIONAL` | `OPTIONAL` | Default token to use for client requests where no token is supplied; this is often configured with read-only access to services to enable DNS service discovery on agents | In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the -[/v1/agent/token API](/api-docs/agent#update-acl-tokens). +[/v1/agent/token API](/consul/api-docs/agent#update-acl-tokens). #### ACL Agent Master Token -Since the [`acl_agent_master_token`](/docs/agent/config/config-files#acl_agent_master_token_legacy) is designed to be used when the Consul servers are not available, its policy is managed locally on the agent and does not need to have a token defined on the Consul servers via the ACL API. Once set, it implicitly has the following policy associated with it (the `node` policy was added in Consul 0.9.0): +Since the [`acl_agent_master_token`](/consul/docs/agent/config/config-files#acl_agent_master_token_legacy) is designed to be used when the Consul servers are not available, its policy is managed locally on the agent and does not need to have a token defined on the Consul servers via the ACL API. Once set, it implicitly has the following policy associated with it (the `node` policy was added in Consul 0.9.0): ```hcl agent "" { @@ -231,15 +231,15 @@ node "" { ``` In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the -[/v1/agent/token API](/api-docs/agent#update-acl-tokens). +[/v1/agent/token API](/consul/api-docs/agent#update-acl-tokens). #### ACL Agent Token -The [`acl_agent_token`](/docs/agent/config/config-files#acl_agent_token) is a special token that is used for an agent's internal operations. It isn't used directly for any user-initiated operations like the [`acl_token`](/docs/agent/config/config-files#acl_token), though if the `acl_agent_token` isn't configured the `acl_token` will be used. The ACL agent token is used for the following operations by the agent: +The [`acl_agent_token`](/consul/docs/agent/config/config-files#acl_agent_token) is a special token that is used for an agent's internal operations. It isn't used directly for any user-initiated operations like the [`acl_token`](/consul/docs/agent/config/config-files#acl_token), though if the `acl_agent_token` isn't configured the `acl_token` will be used. The ACL agent token is used for the following operations by the agent: -1. Updating the agent's node entry using the [Catalog API](/api-docs/catalog), including updating its node metadata, tagged addresses, and network coordinates -2. Performing [anti-entropy](/docs/architecture/anti-entropy) syncing, in particular reading the node metadata and services registered with the catalog -3. Reading and writing the special `_rexec` section of the KV store when executing [`consul exec`](/commands/exec) commands +1. Updating the agent's node entry using the [Catalog API](/consul/api-docs/catalog), including updating its node metadata, tagged addresses, and network coordinates +2. Performing [anti-entropy](/consul/docs/architecture/anti-entropy) syncing, in particular reading the node metadata and services registered with the catalog +3. Reading and writing the special `_rexec` section of the KV store when executing [`consul exec`](/consul/commands/exec) commands Here's an example policy sufficient to accomplish the above for a node called `mynode`: @@ -255,10 +255,10 @@ key "_rexec" { } ``` -The `service` policy needs `read` access for any services that can be registered on the agent. If [remote exec is disabled](/docs/agent/config/config-files#disable_remote_exec), the default, then the `key` policy can be omitted. +The `service` policy needs `read` access for any services that can be registered on the agent. If [remote exec is disabled](/consul/docs/agent/config/config-files#disable_remote_exec), the default, then the `key` policy can be omitted. In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the -[/v1/agent/token API](/api-docs/agent#update-acl-tokens). +[/v1/agent/token API](/consul/api-docs/agent#update-acl-tokens). ## Bootstrapping ACLs @@ -271,7 +271,7 @@ The first step for bootstrapping ACLs is to enable ACLs on the Consul servers in datacenter. In this example, we are configuring the following: 1. An ACL datacenter of "dc1", which is where these servers are -2. An ACL master token of "b1gs33cr3t"; see below for an alternative using the [/v1/acl/bootstrap API](/api-docs/acl#bootstrap-acls) +2. An ACL master token of "b1gs33cr3t"; see below for an alternative using the [/v1/acl/bootstrap API](/consul/api-docs/acl#bootstrap-acls) 3. A default policy of "deny" which means we are in allowlist mode 4. A down policy of "extend-cache" which means that we will ignore token TTLs during an outage @@ -291,15 +291,15 @@ The servers will need to be restarted to load the new configuration. Please take to start the servers one at a time, and ensure each server has joined and is operating correctly before starting another. -The [`acl_master_token`](/docs/agent/config/config-files#acl_master_token) will be created +The [`acl_master_token`](/consul/docs/agent/config/config-files#acl_master_token) will be created as a "management" type token automatically. The -[`acl_master_token`](/docs/agent/config/config-files#acl_master_token) is only installed when +[`acl_master_token`](/consul/docs/agent/config/config-files#acl_master_token) is only installed when a server acquires cluster leadership. If you would like to install or change the -[`acl_master_token`](/docs/agent/config/config-files#acl_master_token), set the new value for -[`acl_master_token`](/docs/agent/config/config-files#acl_master_token) in the configuration +[`acl_master_token`](/consul/docs/agent/config/config-files#acl_master_token), set the new value for +[`acl_master_token`](/consul/docs/agent/config/config-files#acl_master_token) in the configuration for all servers. Once this is done, restart the current leader to force a leader election. -In Consul 0.9.1 and later, you can use the [/v1/acl/bootstrap API](/api-docs/acl#bootstrap-acls) +In Consul 0.9.1 and later, you can use the [/v1/acl/bootstrap API](/consul/api-docs/acl#bootstrap-acls) to make the initial master token, so a token never needs to be placed into a configuration file. To use this approach, omit `acl_master_token` from the above config and then call the API: @@ -316,7 +316,7 @@ It's only possible to bootstrap one time, and bootstrapping will be disabled if token was configured and created. Once the ACL system is bootstrapped, ACL tokens can be managed through the -[ACL API](/api-docs/acl). +[ACL API](/consul/api-docs/acl). #### Create an Agent Token @@ -329,9 +329,9 @@ servers related to permission denied errors: ``` These errors are because the agent doesn't yet have a properly configured -[`acl_agent_token`](/docs/agent/config/config-files#acl_agent_token) that it can use for its +[`acl_agent_token`](/consul/docs/agent/config/config-files#acl_agent_token) that it can use for its own internal operations like updating its node information in the catalog and performing -[anti-entropy](/docs/architecture/anti-entropy) syncing. We can create a token using the +[anti-entropy](/consul/docs/architecture/anti-entropy) syncing. We can create a token using the ACL API, and the ACL master token we set in the previous step: ```shell-session @@ -415,7 +415,7 @@ environment it is recommended that each client get an ACL agent token with `node privileges for just its own node name prefix, and `service` read privileges for just the service prefixes expected to be registered on that client. -[Anti-entropy](/docs/architecture/anti-entropy) syncing requires the ACL agent token +[Anti-entropy](/consul/docs/architecture/anti-entropy) syncing requires the ACL agent token to have `service` read privileges for all services that may be registered with the agent, so generally an empty `service` prefix can be used, as shown in the example. @@ -547,20 +547,20 @@ The next section shows an alternative to the anonymous token. #### Set Agent-Specific Default Tokens (Optional) -An alternative to the anonymous token is the [`acl_token`](/docs/agent/config/config-files#acl_token) +An alternative to the anonymous token is the [`acl_token`](/consul/docs/agent/config/config-files#acl_token) configuration item. When a request is made to a particular Consul agent and no token is -supplied, the [`acl_token`](/docs/agent/config/config-files#acl_token) will be used for the token, +supplied, the [`acl_token`](/consul/docs/agent/config/config-files#acl_token) will be used for the token, instead of being left empty which would normally invoke the anonymous token. In Consul 0.9.1 and later, the agent ACL tokens can be introduced or updated via the -[/v1/agent/token API](/api-docs/agent#update-acl-tokens). +[/v1/agent/token API](/consul/api-docs/agent#update-acl-tokens). This behaves very similarly to the anonymous token, but can be configured differently on each agent, if desired. For example, this allows more fine grained control of what DNS requests a given agent can service, or can give the agent read access to some key-value store prefixes by default. -If using [`acl_token`](/docs/agent/config/config-files#acl_token), then it's likely the anonymous +If using [`acl_token`](/consul/docs/agent/config/config-files#acl_token), then it's likely the anonymous token will have a more restrictive policy than shown in the examples here. #### Create Tokens for UI Use (Optional) @@ -588,11 +588,11 @@ The token can then be set on the "settings" page of the UI. #### Next Steps The examples above configure a basic ACL environment with the ability to see all nodes -by default, and limited access to just the "consul" service. The [ACL API](/api-docs/acl) +by default, and limited access to just the "consul" service. The [ACL API](/consul/api-docs/acl) can be used to create tokens for applications specific to their intended use, and to create more specific ACL agent tokens for each agent's expected role. -Also see [HashiCorp's Vault](https://www.vaultproject.io/docs/secrets/consul), which +Also see [HashiCorp's Vault](/vault/docs/secrets/consul), which has an integration with Consul that allows it to generate ACL tokens on the fly and to manage their lifetimes. @@ -655,7 +655,7 @@ This is equivalent to the following JSON input: } ``` -The [ACL API](/api-docs/acl) allows either HCL or JSON to be used to define the content +The [ACL API](/consul/api-docs/acl) allows either HCL or JSON to be used to define the content of the rules section. Here's a sample request using the HCL form: @@ -701,7 +701,7 @@ or the `CONSUL_HTTP_TOKEN` environment variable. #### Agent Rules -The `agent` policy controls access to the utility operations in the [Agent API](/api-docs/agent), +The `agent` policy controls access to the utility operations in the [Agent API](/consul/api-docs/agent), such as join and leave. All of the catalog-related operations are covered by the [`node`](#node-rules) and [`service`](#service-rules) policies instead. @@ -724,14 +724,14 @@ the example above, the rules allow read-only access to any node name with the em read-write access to any node name that starts with "foo", and deny all access to any node name that starts with "bar". -Since [Agent API](/api-docs/agent) utility operations may be required before an agent is joined to +Since [Agent API](/consul/api-docs/agent) utility operations may be required before an agent is joined to a cluster, or during an outage of the Consul servers or ACL datacenter, a special token may be -configured with [`acl_agent_master_token`](/docs/agent/config/config-files#acl_agent_master_token) to allow +configured with [`acl_agent_master_token`](/consul/docs/agent/config/config-files#acl_agent_master_token) to allow write access to these operations even if no ACL resolution capability is available. #### Event Rules -The `event` policy controls access to event operations in the [Event API](/api-docs/event), such as +The `event` policy controls access to event operations in the [Event API](/consul/api-docs/event), such as firing events and listing events. Event rules look like this: @@ -749,14 +749,14 @@ Event rules are keyed by the event name prefix they apply to, using the longest In the example above, the rules allow read-only access to any event, and firing of any event that starts with "deploy". -The [`consul exec`](/commands/exec) command uses events with the "\_rexec" prefix during +The [`consul exec`](/consul/commands/exec) command uses events with the "\_rexec" prefix during operation, so to enable this feature in a Consul environment with ACLs enabled, you will need to give agents a token with access to this event prefix, in addition to configuring -[`disable_remote_exec`](/docs/agent/config/config-files#disable_remote_exec) to `false`. +[`disable_remote_exec`](/consul/docs/agent/config/config-files#disable_remote_exec) to `false`. #### Key/Value Rules -The `key` policy controls access to key/value store operations in the [KV API](/api-docs/kv). Key +The `key` policy controls access to key/value store operations in the [KV API](/consul/api-docs/kv). Key rules look like this: ```hcl @@ -780,7 +780,7 @@ starts with "bar". Consul 1.0 introduces a new `list` policy for keys that is only enforced when opted in via the boolean config param "acl_enable_key_list_policy". `list` controls access to recursively list entries and keys, and enables more fine grained policies. With "acl_enable_key_list_policy", -recursive reads via [the KV API](/api-docs/kv#recurse) with an invalid token result in a 403. Example: +recursive reads via [the KV API](/consul/api-docs/kv#recurse) with an invalid token result in a 403. Example: ```hcl key "" { @@ -819,12 +819,12 @@ EOF } ``` -For more detailed information, see the [Consul Sentinel documentation](/docs/agent/sentinel). +For more detailed information, see the [Consul Sentinel documentation](/consul/docs/agent/sentinel). #### Keyring Rules The `keyring` policy controls access to keyring operations in the -[Keyring API](/api-docs/operator/keyring). +[Keyring API](/consul/api-docs/operator/keyring). Keyring rules look like this: @@ -837,8 +837,8 @@ dispositions. In the example above, the keyring may be read and updated. #### Node Rules -The `node` policy controls node-level registration and read access to the [Catalog API](/api-docs/catalog), -service discovery with the [Health API](/api-docs/health), and filters results in [Agent API](/api-docs/agent) +The `node` policy controls node-level registration and read access to the [Catalog API](/consul/api-docs/catalog), +service discovery with the [Health API](/consul/api-docs/health), and filters results in [Agent API](/consul/api-docs/agent) operations like fetching the list of cluster members. Node rules look like this: @@ -860,43 +860,43 @@ the example above, the rules allow read-only access to any node name with the em read-write access to any node name that starts with "app", and deny all access to any node name that starts with "admin". -Agents need to be configured with an [`acl_agent_token`](/docs/agent/config/config-files#acl_agent_token) +Agents need to be configured with an [`acl_agent_token`](/consul/docs/agent/config/config-files#acl_agent_token) with at least "write" privileges to their own node name in order to register their information with the catalog, such as node metadata and tagged addresses. If this is configured incorrectly, the agent will print an error to the console when it tries to sync its state with the catalog. Consul's DNS interface is also affected by restrictions on node rules. If the -[`acl_token`](/docs/agent/config/config-files#acl_token) used by the agent does not have "read" access to a +[`acl_token`](/consul/docs/agent/config/config-files#acl_token) used by the agent does not have "read" access to a given node, then the DNS interface will return no records when queried for it. When reading from the catalog or retrieving information from the health endpoints, node rules are used to filter the results of the query. This allows for configurations where a token has access to a given service name, but only on an allowed subset of node names. -Node rules come into play when using the [Agent API](/api-docs/agent) to register node-level +Node rules come into play when using the [Agent API](/consul/api-docs/agent) to register node-level checks. The agent will check tokens locally as a check is registered, and Consul also performs -periodic [anti-entropy](/docs/architecture/anti-entropy) syncs, which may require an +periodic [anti-entropy](/consul/docs/architecture/anti-entropy) syncs, which may require an ACL token to complete. To accommodate this, Consul provides two methods of configuring ACL tokens to use for registration events: -1. Using the [acl_token](/docs/agent/config/config-files#acl_token) configuration +1. Using the [acl_token](/consul/docs/agent/config/config-files#acl_token) configuration directive. This allows a single token to be configured globally and used during all check registration operations. 2. Providing an ACL token with service and check definitions at registration time. This allows for greater flexibility and enables the use of multiple tokens on the same agent. Examples of what this looks like are - available for both [services](/docs/discovery/services) and - [checks](/docs/discovery/checks). Tokens may also be passed to the - [HTTP API](/api-docs) for operations that require them. + available for both [services](/consul/docs/discovery/services) and + [checks](/consul/docs/discovery/checks). Tokens may also be passed to the + [HTTP API](/consul/api-docs) for operations that require them. In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with -[`enable_script_checks`](/docs/agent/config/config-files#enable_script_checks) set to `true` in order to enable +[`enable_script_checks`](/consul/docs/agent/config/config-files#enable_script_checks) set to `true` in order to enable script checks. #### Operator Rules The `operator` policy controls access to cluster-level operations in the -[Operator API](/api-docs/operator), other than the [Keyring API](/api-docs/operator/keyring). +[Operator API](/consul/api-docs/operator), other than the [Keyring API](/consul/api-docs/operator/keyring). Operator rules look like this: @@ -911,7 +911,7 @@ diagnostic purposes but not make any changes. #### Prepared Query Rules The `query` policy controls access to create, update, and delete prepared queries in the -[Prepared Query API](/api-docs/query). Executing queries is subject to `node` and `service` +[Prepared Query API](/consul/api-docs/query). Executing queries is subject to `node` and `service` policies, as will be explained below. Query rules look like this: @@ -954,7 +954,7 @@ here, with examples: that is used and known by many clients to provide geo-failover behavior for a database. -- [Template queries](/api-docs/query#prepared-query-templates) +- [Template queries](/consul/api-docs/query#prepared-query-templates) queries work like static queries with a `Name` defined, except that a catch-all template with an empty `Name` requires an ACL token that can write to any query prefix. @@ -1001,8 +1001,8 @@ These differences are outlined in the table below: #### Service Rules -The `service` policy controls service-level registration and read access to the [Catalog API](/api-docs/catalog) -and service discovery with the [Health API](/api-docs/health). +The `service` policy controls service-level registration and read access to the [Catalog API](/consul/api-docs/catalog) +and service discovery with the [Health API](/consul/api-docs/health). Service rules look like this: @@ -1024,40 +1024,40 @@ read-write access to any service name that starts with "app", and deny all acces starts with "admin". Consul's DNS interface is affected by restrictions on service rules. If the -[`acl_token`](/docs/agent/config/config-files#acl_token) used by the agent does not have "read" access to a +[`acl_token`](/consul/docs/agent/config/config-files#acl_token) used by the agent does not have "read" access to a given service, then the DNS interface will return no records when queried for it. When reading from the catalog or retrieving information from the health endpoints, service rules are used to filter the results of the query. -Service rules come into play when using the [Agent API](/api-docs/agent) to register services or +Service rules come into play when using the [Agent API](/consul/api-docs/agent) to register services or checks. The agent will check tokens locally as a service or check is registered, and Consul also -performs periodic [anti-entropy](/docs/architecture/anti-entropy) syncs, which may require an +performs periodic [anti-entropy](/consul/docs/architecture/anti-entropy) syncs, which may require an ACL token to complete. To accommodate this, Consul provides two methods of configuring ACL tokens to use for registration events: -1. Using the [acl_token](/docs/agent/config/config-files#acl_token) configuration +1. Using the [acl_token](/consul/docs/agent/config/config-files#acl_token) configuration directive. This allows a single token to be configured globally and used during all service and check registration operations. 2. Providing an ACL token with service and check definitions at registration time. This allows for greater flexibility and enables the use of multiple tokens on the same agent. Examples of what this looks like are available for - both [services](/docs/discovery/services) and - [checks](/docs/discovery/checks). Tokens may also be passed to the [HTTP - API](/api-docs) for operations that require them. **Note:** all tokens + both [services](/consul/docs/discovery/services) and + [checks](/consul/docs/discovery/checks). Tokens may also be passed to the [HTTP + API](/consul/api-docs) for operations that require them. **Note:** all tokens passed to an agent are persisted on local disk to allow recovery from restarts. See [`-data-dir` flag - documentation](/docs/agent/config/config-files#acl_token) for notes on securing + documentation](/consul/docs/agent/config/config-files#acl_token) for notes on securing access. In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with -[`enable_script_checks`](/docs/agent/config/config-files#enable_script_checks) or -[`enable_local_script_checks`](/docs/agent/config/config-files#enable_local_script_checks) +[`enable_script_checks`](/consul/docs/agent/config/config-files#enable_script_checks) or +[`enable_local_script_checks`](/consul/docs/agent/config/config-files#enable_local_script_checks) set to `true` in order to enable script checks. #### Session Rules -The `session` policy controls access to [Session API](/api-docs/session) operations. +The `session` policy controls access to [Session API](/consul/api-docs/session) operations. Session rules look like this: @@ -1083,22 +1083,22 @@ name that starts with "admin". #### Outages and ACL Replication ((#replication)) The Consul ACL system is designed with flexible rules to accommodate for an outage -of the [`acl_datacenter`](/docs/agent/config/config-files#acl_datacenter) or networking +of the [`acl_datacenter`](/consul/docs/agent/config/config-files#acl_datacenter) or networking issues preventing access to it. In this case, it may be impossible for agents in non-authoritative datacenters to resolve tokens. Consul provides -a number of configurable [`acl_down_policy`](/docs/agent/config/config-files#acl_down_policy) +a number of configurable [`acl_down_policy`](/consul/docs/agent/config/config-files#acl_down_policy) choices to tune behavior. It is possible to deny or permit all actions or to ignore cache TTLs and enter a fail-safe mode. The default is to ignore cache TTLs for any previously resolved tokens and to deny any uncached tokens. Consul 0.7 added an ACL Replication capability that can allow non-authoritative datacenter agents to resolve even uncached tokens. This is enabled by setting an -[`acl_replication_token`](/docs/agent/config/config-files#acl_replication_token) in the +[`acl_replication_token`](/consul/docs/agent/config/config-files#acl_replication_token) in the configuration on the servers in the non-authoritative datacenters. In Consul 0.9.1 and later you can enable ACL replication using -[`enable_acl_replication`](/docs/agent/config/config-files#enable_acl_replication) and +[`enable_acl_replication`](/consul/docs/agent/config/config-files#enable_acl_replication) and then set the token later using the -[agent token API](/api-docs/agent#update-acl-tokens) on each server. This can +[agent token API](/consul/api-docs/agent#update-acl-tokens) on each server. This can also be used to rotate the token without restarting the Consul servers. With replication enabled, the servers will maintain a replica of the authoritative @@ -1112,9 +1112,9 @@ every 30 seconds. Replicated changes are written at a rate that's throttled to a large set of ACLs. If there's a partition or other outage affecting the authoritative datacenter, -and the [`acl_down_policy`](/docs/agent/config/config-files#acl_down_policy) +and the [`acl_down_policy`](/consul/docs/agent/config/config-files#acl_down_policy) is set to "extend-cache", tokens will be resolved during the outage using the -replicated set of ACLs. An [ACL replication status](/api-docs/acl#check-acl-replication) +replicated set of ACLs. An [ACL replication status](/consul/api-docs/acl#check-acl-replication) endpoint is available to monitor the health of the replication process. Also note that in recent versions of Consul (greater than 1.2.0), using `acl_down_policy = "async-cache"` refreshes token asynchronously when an ACL is @@ -1122,7 +1122,7 @@ already cached and is expired while similar semantics than "extend-cache". It allows to avoid having issues when connectivity with the authoritative is not completely broken, but very slow. -Locally-resolved ACLs will be cached using the [`acl_ttl`](/docs/agent/config/config-files#acl_ttl) +Locally-resolved ACLs will be cached using the [`acl_ttl`](/consul/docs/agent/config/config-files#acl_ttl) setting of the non-authoritative datacenter, so these entries may persist in the cache for up to the TTL, even after the authoritative datacenter comes back online. @@ -1132,7 +1132,7 @@ using a process like this: 1. Enable ACL replication in all datacenters to allow continuation of service during the migration, and to populate the target datacenter. Verify replication is healthy and caught up to the current ACL index in the target datacenter - using the [ACL replication status](/api-docs/acl#check-acl-replication) + using the [ACL replication status](/consul/api-docs/acl#check-acl-replication) endpoint. 2. Turn down the old authoritative datacenter servers. 3. Rolling restart the agents in the target datacenter and change the @@ -1148,7 +1148,7 @@ Consul 0.8 added many more ACL policy types and brought ACL enforcement to Consu agents for the first time. To ease the transition to Consul 0.8 for existing ACL users, there's a configuration option to disable these new features. To disable support for these new ACLs, set the -[`acl_enforce_version_8`](/docs/agent/config/config-files#acl_enforce_version_8) configuration +[`acl_enforce_version_8`](/consul/docs/agent/config/config-files#acl_enforce_version_8) configuration option to `false` on Consul clients and servers. Here's a summary of the new features: @@ -1171,31 +1171,31 @@ Here's a summary of the new features: Two new configuration options are used once version 8 ACLs are enabled: -- [`acl_agent_master_token`](/docs/agent/config/config-files#acl_agent_master_token) is used as +- [`acl_agent_master_token`](/consul/docs/agent/config/config-files#acl_agent_master_token) is used as a special access token that has `agent` ACL policy `write` privileges on each agent where it is configured, as well as `node` ACL policy `read` privileges for all nodes. This token should only be used by operators during outages when Consul servers aren't available to resolve ACL tokens. Applications should use regular ACL tokens during normal operation. -- [`acl_agent_token`](/docs/agent/config/config-files#acl_agent_token) is used internally by +- [`acl_agent_token`](/consul/docs/agent/config/config-files#acl_agent_token) is used internally by Consul agents to perform operations to the service catalog when registering themselves or sending network coordinates to the servers. This token must at least have `node` ACL policy `write` access to the node name it will register as in order to register any node-level information like metadata or tagged addresses. -Since clients now resolve ACLs locally, the [`acl_down_policy`](/docs/agent/config/config-files#acl_down_policy) +Since clients now resolve ACLs locally, the [`acl_down_policy`](/consul/docs/agent/config/config-files#acl_down_policy) now applies to Consul clients as well as Consul servers. This will determine what the client will do in the event that the servers are down. -Consul clients must have [`acl_datacenter`](/docs/agent/config/config-files#acl_datacenter) configured +Consul clients must have [`acl_datacenter`](/consul/docs/agent/config/config-files#acl_datacenter) configured in order to enable agent-level ACL features. If this is set, the agents will contact the Consul servers to determine if ACLs are enabled at the cluster level. If they detect that ACLs are not enabled, they will check at most every 2 minutes to see if they have become enabled, and will start enforcing ACLs automatically. If an agent has an `acl_datacenter` defined, operators will -need to use the [`acl_agent_master_token`](/docs/agent/config/config-files#acl_agent_master_token) to +need to use the [`acl_agent_master_token`](/consul/docs/agent/config/config-files#acl_agent_master_token) to perform agent-level operations if the Consul servers aren't present (such as for a manual join -to the cluster), unless the [`acl_down_policy`](/docs/agent/config/config-files#acl_down_policy) on the +to the cluster), unless the [`acl_down_policy`](/consul/docs/agent/config/config-files#acl_down_policy) on the agent is set to "allow". Non-server agents do not need to have the -[`acl_master_token`](/docs/agent/config/config-files#acl_master_token) configured; it is not +[`acl_master_token`](/consul/docs/agent/config/config-files#acl_master_token) configured; it is not used by agents in any way. diff --git a/website/content/docs/security/acl/acl-migrate-tokens.mdx b/website/content/docs/security/acl/acl-migrate-tokens.mdx index b09891fb48..33baf4eff8 100644 --- a/website/content/docs/security/acl/acl-migrate-tokens.mdx +++ b/website/content/docs/security/acl/acl-migrate-tokens.mdx @@ -54,7 +54,7 @@ blank `AccessorID`. In addition, it is assumed that all clients that might _create_ ACL tokens (e.g. Vault's Consul secrets engine) have been updated to use the [new ACL -APIs](/api-docs/acl/tokens). +APIs](/consul/api-docs/acl/tokens). Specifically if you are using Vault's Consul secrets engine you need to be running Vault 1.0.0 or higher, _and_ you must update all roles defined in Vault @@ -78,7 +78,7 @@ have. The simplest and most automatic strategy is to create one new policy for every existing token. This is easy to automate, but may result in a lot of policies with exactly the same rules and with non-human-readable names which will make -managing policies harder. This approach can be accomplished using the [`consul acl policy create`](/commands/acl/policy/create) command with +managing policies harder. This approach can be accomplished using the [`consul acl policy create`](/consul/commands/acl/policy/create) command with `-from-token` option. | Pros | Cons | @@ -107,7 +107,7 @@ semantics of the old ACL system. To assist with this approach, there is a CLI tool and corresponding API that can translate a legacy ACL token's rules into a new ACL policy that is exactly -equivalent. See [`consul acl translate-rules`](/commands/acl/translate-rules). +equivalent. See [`consul acl translate-rules`](/consul/commands/acl/translate-rules). | Pros | Cons | | ------------------------------------------------- | ------------------------------------------------------------------ | @@ -130,13 +130,13 @@ necessary access for existing clients; this is up to the operator to ensure. #### Update via API -Use the [`PUT /v1/acl/token/:AccessorID`](/api-docs/acl/tokens#update-a-token) +Use the [`PUT /v1/acl/token/:AccessorID`](/consul/api-docs/acl/tokens#update-a-token) endpoint. Specifically, ensure that the `Rules` field is omitted or empty. Empty `Rules` indicates that this is now treated as a new token. #### Update via CLI -Use the [`consul acl token update`](/commands/acl/token/update) +Use the [`consul acl token update`](/consul/commands/acl/token/update) command to update the token. Specifically you need to use `-upgrade-legacy` which will ensure that legacy rules are removed as well as the new policies added. diff --git a/website/content/docs/security/acl/acl-policies.mdx b/website/content/docs/security/acl/acl-policies.mdx index cb6dd3fe6b..f5d005ffbb 100644 --- a/website/content/docs/security/acl/acl-policies.mdx +++ b/website/content/docs/security/acl/acl-policies.mdx @@ -11,7 +11,7 @@ This topic describes policies, which are components in Consul's access control l ## Introduction -A policy is a group of one or more ACL rules that are linked to [ACL tokens](/docs/security/acl/acl-tokens). The following diagram describes the relationships between rules, policies, and tokens: +A policy is a group of one or more ACL rules that are linked to [ACL tokens](/consul/docs/security/acl/acl-tokens). The following diagram describes the relationships between rules, policies, and tokens: ![ACL system component relationships](/img/acl-token-policy-rule-relationship.png) @@ -21,7 +21,7 @@ The term "policy" should not be confused with the keyword `policy`. The keyword Rules are one of several [attributes that form a policy](#policy-attributes). They are building blocks that define access to resources. -This section describes about how to assemble rules into policies. Refer to the [ACL Rules Reference](/docs/security/acl/acl-rules) for additional details about how to configure rules and how they affect access to resources. +This section describes about how to assemble rules into policies. Refer to the [ACL Rules Reference](/consul/docs/security/acl/acl-rules) for additional details about how to configure rules and how they affect access to resources. ### Rule Specification @@ -104,7 +104,7 @@ Use the `policy` keyword and one of the following access levels to set a policy - `write`: Allows the resource to be read and modified. - `deny`: Denies read and write access to the resource. -The special `list` access level provides access to all keys with the specified resource label in the [Consul KV](/commands/kv/). The `list` access level can only be used with the `key_prefix` resource. The [`acl.enable_key_list_policy`](/docs/agent/config/config-files#acl_enable_key_list_policy) setting must be set to `true`. +The special `list` access level provides access to all keys with the specified resource label in the [Consul KV](/consul/commands/kv/). The `list` access level can only be used with the `key_prefix` resource. The [`acl.enable_key_list_policy`](/consul/docs/agent/config/config-files#acl_enable_key_list_policy) setting must be set to `true`. ### Matching and Prefix Values @@ -246,7 +246,7 @@ operator = "read" ## Rule Scope The rules from all policies, including roles and service identities, linked with a token are combined to form that token's effective rule set. -Policy rules can be defined in either an `allowlist` or `denylist` mode, depending on the configuration of the [`acl_default_policy`](/docs/agent/config/config-files#acl_default_policy). +Policy rules can be defined in either an `allowlist` or `denylist` mode, depending on the configuration of the [`acl_default_policy`](/consul/docs/agent/config/config-files#acl_default_policy). If the default policy is configured to deny access to all resources, then you can specify `allowlist` in policy rules to explicitly allow access to resources. Conversely, if the default policy is configured to allow access to all resources, then you can specify `denylist` in policy rules to explicitly deny access to resources. @@ -256,7 +256,7 @@ After defining policies, the person responsible for administrating ACLs in your ### Command Line -Use the `consul acl policy` command to manage policies. Refer to the [ACL command line documentation](/commands/acl/policy) for details. +Use the `consul acl policy` command to manage policies. Refer to the [ACL command line documentation](/consul/commands/acl/policy) for details. The following example creates a policy called `my-app-policy` and applies the rules defined in `rules.hcl`: @@ -279,7 +279,7 @@ You can can define several attributes that attach additional metadata and specif ### HTTP API Endpoint -The endpoint takes data formatted in HCL or JSON. Refer to the [ACL HTTP API endpoint documentation](/api-docs/acl) for details about the API. +The endpoint takes data formatted in HCL or JSON. Refer to the [ACL HTTP API endpoint documentation](/consul/api-docs/acl) for details about the API. The following example adds a set of rules to a policy called `my-app-policy`. The policy defines access to the `key` resource (Consul K/V). The rules are formatted in HCL, but they are wrapped in JSON so that the data can be sent using cURL: @@ -324,9 +324,9 @@ The policy configuration is returned when the call is successfully performed: A policy that has been implemented must still be linked to a token before the policy has an effect. A service or agent presents the token when interacting with resources in the network. The ACL system processes evaluate the policies linked to the token to determine if the requester has access to the requested resource. -The person responsible for administrating ACLs can use the command line or call the API endpoint to link policies to tokens. Tokens can also be generated dynamically from an external system using Consul's [auth methods](/docs/security/acl/auth-methods) functionality. +The person responsible for administrating ACLs can use the command line or call the API endpoint to link policies to tokens. Tokens can also be generated dynamically from an external system using Consul's [auth methods](/consul/docs/security/acl/auth-methods) functionality. -Refer to the [tokens documentation](/docs/security/acl/acl-tokens), as well as the [ACL tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production#create-the-agent-token), for details about creating and linking policies to tokens. +Refer to the [tokens documentation](/consul/docs/security/acl/acl-tokens), as well as the [ACL tutorial](/consul/tutorials/security/access-control-setup-production#create-the-agent-token), for details about creating and linking policies to tokens. ## Policy Attributes @@ -336,8 +336,8 @@ Additional metadata, such as the values of the `ID` and `name` fields, provide h Refer to the following topics for additional information: -- [Namespaces](/docs/enterprise/namespaces) -- [Admin Partitions](/docs/enterprise/admin-partitions) +- [Namespaces](/consul/docs/enterprise/namespaces) +- [Admin Partitions](/consul/docs/enterprise/admin-partitions) ACL policies can have the following attributes: @@ -346,12 +346,12 @@ ACL policies can have the following attributes: | `ID` | The policy's public identifier. Present the `ID` (or the `name`) value when interacting with policies. You can specify a value when creating policies or use the value auto-generated by Consul. | N/A | N/A | | `name` | Unique name for the policy. | Required | none | | `description` | Human readable description of the policy. | Optional | none | -| `rules` | Set of rules granting or denying permissions. See the [Rule Specification](/docs/security/acl/acl-rules#rule-specification) documentation for more details. | Optional | none | +| `rules` | Set of rules granting or denying permissions. See the [Rule Specification](/consul/docs/security/acl/acl-rules#rule-specification) documentation for more details. | Optional | none | | `datacenter` | Datacenter in which the policy is valid. More than one datacenter can be specified. | Optional | none | | `namespace` | Namespace in which the policy is valid. Added in Consul Enterprise 1.7.0. | Optional | `default` | | `partition` | Admin partition in which the policy is valid. Added in Consul Enterprise 1.11.0 | Optional | `default` | --> **Non-default Namespaces and Partitions** - Rules defined in a policy tied to an namespace or admin partition other than `default` can only grant a subset of privileges that affect the namespace or partition. See [Namespace Rules](/docs/security/acl/acl-rules#namespace-rules) and [Admin Partition Rules](/docs/security/acl/acl-rules#admin-partition-rules) for additional information. +-> **Non-default Namespaces and Partitions** - Rules defined in a policy tied to an namespace or admin partition other than `default` can only grant a subset of privileges that affect the namespace or partition. See [Namespace Rules](/consul/docs/security/acl/acl-rules#namespace-rules) and [Admin Partition Rules](/consul/docs/security/acl/acl-rules#admin-partition-rules) for additional information. You can view the current ACL policies on the command line or through the API. The following example demonstrates the command line usage: @@ -403,7 +403,7 @@ This section includes example policy configurations for achieving specific use-c ### Enable the Snapshot Agent to Run on a Specific Node -The `consul snapshot agent` command starts a process that takes snapshots of the state of the Consul servers and either saves them locally or pushes them to a remote storage service. Refer to [Consul Snapshot Agent](/commands/snapshot/agent) for additional information. +The `consul snapshot agent` command starts a process that takes snapshots of the state of the Consul servers and either saves them locally or pushes them to a remote storage service. Refer to [Consul Snapshot Agent](/consul/commands/snapshot/agent) for additional information. In the following example, the ACL policy enables the snapshot agent to run on a node named `server-1234`. @@ -453,7 +453,7 @@ service "consul-snapshot" { ### Enable Vault to Access the Consul Storage Backend -If you are using [Vault](https://www.vaultproject.io/docs) to manage secrets in your infrastructure, you can configure Vault to use Consul's key/value (KV) store as backend storage to persist Vault's data. Refer to the [Consul KV documentation](/docs/dynamic-app-config/kv) and the [Vault storage documentation](https://www.vaultproject.io/docs/configuration/storage) for additional information. +If you are using [Vault](/vault/docs) to manage secrets in your infrastructure, you can configure Vault to use Consul's key/value (KV) store as backend storage to persist Vault's data. Refer to the [Consul KV documentation](/consul/docs/dynamic-app-config/kv) and the [Vault storage documentation](/vault/docs/configuration/storage) for additional information. In the following example, the ACL policy enables Vault to register as a service and provides access to the `vault/` path in Consul's KV store. diff --git a/website/content/docs/security/acl/acl-roles.mdx b/website/content/docs/security/acl/acl-roles.mdx index d76147aedc..0f451596c9 100644 --- a/website/content/docs/security/acl/acl-roles.mdx +++ b/website/content/docs/security/acl/acl-roles.mdx @@ -16,7 +16,7 @@ As a result, roles can provide a more convenient authentication infrastructure t Roles are configurations linking several policies to a token. The following procedure describes the workflow for implementing roles. -1. Assemble rules into policies (see [Policies](/docs/security/acl/acl-policies)) and register them in Consul. +1. Assemble rules into policies (see [Policies](/consul/docs/security/acl/acl-policies)) and register them in Consul. 1. Define a role and include the policy IDs or names. 1. Register the role in Consul and link it to a token. 1. Distribute the tokens to users for implementation. @@ -41,7 +41,7 @@ Issue the `consul acl role create` command to create roles. In the following exa $ consul acl role create -name "crawler" -description "web crawler role" -policy-name "crawler-kv" -policy-name "crawler-key" ``` -Refer to the [command line documentation](/commands/acl/role) for details. +Refer to the [command line documentation](/consul/commands/acl/role) for details. ### API @@ -51,7 +51,7 @@ Make a `PUT` call to the `acl/role` endpoint and specify the role configuration $ curl --request PUT --data @payload.json http://127.0.0.1:8500/v1/acl/role ``` -Refer to the [API documentation](/api-docs/acl/roles) for details. +Refer to the [API documentation](/consul/api-docs/acl/roles) for details. ## Role Attributes @@ -63,8 +63,8 @@ Roles may contain the following attributes: - `Policies`: Specifies a the list of policies that are applicable for the role. The object can reference the policy `ID` or `Name` attribute. - `ServiceIdentities`: Specifies a list of services that are applicable for the role. See [Service Identities](#service-identities) for details. - `NodeIdentities`: Specifies a list of nodes that are applicable for the role. See [Node Identities](#node-identities) for details. -- `Namespace`: The namespace that the policy resides in. Roles can only be linked to policies that are defined in the same namespace. See [Namespaces](/docs/enterprise/namespaces) for additional information. Requires Consul Enterprise 1.7.0+ -- `Partition`: The admin partition that the policy resides in. Roles can only be linked to policies that are defined in the same admin partition. See [Admin Partitions](/docs/enterprise/admin-partitions) for additional information. Requires Consul Enterprise 1.10.0+. +- `Namespace`: The namespace that the policy resides in. Roles can only be linked to policies that are defined in the same namespace. See [Namespaces](/consul/docs/enterprise/namespaces) for additional information. Requires Consul Enterprise 1.7.0+ +- `Partition`: The admin partition that the policy resides in. Roles can only be linked to policies that are defined in the same admin partition. See [Admin Partitions](/consul/docs/enterprise/admin-partitions) for additional information. Requires Consul Enterprise 1.10.0+. ## Service Identities @@ -72,7 +72,7 @@ Roles may contain the following attributes: You can specify a service identity when configuring roles or linking tokens to policies. Service identities enable you to quickly construct policies for services, rather than creating identical polices for each service. -Service identities are used during the authorization process to automatically generate a policy for the service(s) specified. The policy will be linked to the role or token so that the service(s) can _be discovered_ and _discover other healthy service instances_ in a service mesh. Refer to the [service mesh](/docs/connect) topic for additional information about Consul service mesh. +Service identities are used during the authorization process to automatically generate a policy for the service(s) specified. The policy will be linked to the role or token so that the service(s) can _be discovered_ and _discover other healthy service instances_ in a service mesh. Refer to the [service mesh](/consul/docs/connect) topic for additional information about Consul service mesh. ### Service Identity Specification @@ -93,7 +93,7 @@ Use the following syntax to define a service identity: - `ServiceIdentities.ServiceName`: String value that specifies the name of the service you want to associate with the policy. - `ServiceIdentities.Datacenters`: Array that specifies the names of datacenters in which the service identity applies. This field is optional. -Refer to the the [API documentation for roles](/api-docs/acl/roles#sample-payload) for additional information and examples. +Refer to the the [API documentation for roles](/consul/api-docs/acl/roles#sample-payload) for additional information and examples. -> **Scope for Namespace and Admin Partition** - In Consul Enterprise, service identities inherit the namespace or admin partition scope of the corresponding ACL token or role. @@ -117,7 +117,7 @@ node_prefix "" { } ``` -Refer to the [rules reference](/docs/security/acl/acl-rules) for information about the rules in the policy. +Refer to the [rules reference](/consul/docs/security/acl/acl-rules) for information about the rules in the policy. ### Example @@ -209,7 +209,7 @@ node_prefix "" { You can specify a node identity when configuring roles or linking tokens to policies. _Node_ commonly refers to a Consul agent, but a node can also be a physical server, cloud instance, virtual machine, or container. -Node identities enable you to quickly construct policies for nodes, rather than manually creating identical polices for each node. They are used during the authorization process to automatically generate a policy for the node(s) specified. You can specify the token linked to the policy in the [`acl_tokens_agent`](/docs/agent/config/config-files#acl_tokens_agent) field when configuring the agent. +Node identities enable you to quickly construct policies for nodes, rather than manually creating identical polices for each node. They are used during the authorization process to automatically generate a policy for the node(s) specified. You can specify the token linked to the policy in the [`acl_tokens_agent`](/consul/docs/agent/config/config-files#acl_tokens_agent) field when configuring the agent. ### Node Identity Specification @@ -230,7 +230,7 @@ Use the following syntax to define a node identity: - `NodeIdentities.NodeName`: String value that specifies the name of the node you want to associate with the policy. - `NodeIdentities.Datacenter`: String value that specifies the name of the datacenter in which the node identity applies. -Refer to the the [API documentation for roles](/api-docs/acl/roles#sample-payload) for additional information and examples. +Refer to the the [API documentation for roles](/consul/api-docs/acl/roles#sample-payload) for additional information and examples. -> **Consul Enterprise Namespacing** - Node Identities can only be applied to tokens and roles in the `default` namespace. The generated policy rules allow for `service:read` permissions on all services in all namespaces. @@ -250,7 +250,7 @@ service_prefix "" { } ``` -Refer to the [rules reference](/docs/security/acl/acl-rules) for information about the rules in the policy. +Refer to the [rules reference](/consul/docs/security/acl/acl-rules) for information about the rules in the policy. ### Example diff --git a/website/content/docs/security/acl/acl-rules.mdx b/website/content/docs/security/acl/acl-rules.mdx index 273d134ff9..e9cd5c8b12 100644 --- a/website/content/docs/security/acl/acl-rules.mdx +++ b/website/content/docs/security/acl/acl-rules.mdx @@ -7,7 +7,7 @@ description: >- # ACL Rules -This topic provides reference information for the types of access control list (ACL) rules you can create and how they affect access to datacenter resources. For details on how to create rules and group them into policies, see [Policies](/docs/security/acl/acl-policies). +This topic provides reference information for the types of access control list (ACL) rules you can create and how they affect access to datacenter resources. For details on how to create rules and group them into policies, see [Policies](/consul/docs/security/acl/acl-policies). ## Overview @@ -15,34 +15,34 @@ The following table provides an overview of the resources you can use to create | Resource | Description | Labels | | ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------ | -| `acl` | Controls access to ACL operations in the [ACL API](/api-docs/acl).
    See [ACL Resource Rules](#acl-resource-rules) for details. | No | +| `acl` | Controls access to ACL operations in the [ACL API](/consul/api-docs/acl).
    See [ACL Resource Rules](#acl-resource-rules) for details. | No | | `partition`
    `partition_prefix` | Controls access to one or more admin partitions.
    See [Admin Partition Rules](#admin-partition-rules) for details. | Yes | -| `agent`
    `agent_prefix` | Controls access to the utility operations in the [Agent API](/api-docs/agent), such as `join` and `leave`.
    See [Agent Rules](#agent-rules) for details. | Yes | -| `event`
    `event_prefix` | Controls access to event operations in the [Event API](/api-docs/event), such as firing and listing events.
    See [Event Rules](#event-rules) for details. | Yes | -| `key`
    `key_prefix`   | Controls access to key/value store operations in the [KV API](/api-docs/kv).
    Can also use the `list` access level when setting the policy disposition.
    Has additional value options in Consul Enterprise for integrating with [Sentinel](https://docs.hashicorp.com/sentinel/consul).
    See [Key/Value Rules](#key-value-rules) for details. | Yes | -| `keyring`       | Controls access to keyring operations in the [Keyring API](/api-docs/operator/keyring).
    See [Keyring Rules](#keyring-rules) for details. | No | +| `agent`
    `agent_prefix` | Controls access to the utility operations in the [Agent API](/consul/api-docs/agent), such as `join` and `leave`.
    See [Agent Rules](#agent-rules) for details. | Yes | +| `event`
    `event_prefix` | Controls access to event operations in the [Event API](/consul/api-docs/event), such as firing and listing events.
    See [Event Rules](#event-rules) for details. | Yes | +| `key`
    `key_prefix`   | Controls access to key/value store operations in the [KV API](/consul/api-docs/kv).
    Can also use the `list` access level when setting the policy disposition.
    Has additional value options in Consul Enterprise for integrating with [Sentinel](https://docs.hashicorp.com/sentinel/consul).
    See [Key/Value Rules](#key-value-rules) for details. | Yes | +| `keyring`       | Controls access to keyring operations in the [Keyring API](/consul/api-docs/operator/keyring).
    See [Keyring Rules](#keyring-rules) for details. | No | | `mesh`       | Provides operator-level permissions for resources in the admin partition, such as ingress gateways or mesh proxy defaults. See [Mesh Rules](#mesh-rules) for details. | No | -| `peering`       | Controls access to cluster peerings in the [Cluster Peering API](/api-docs/peering). For more details, refer to [Peering Rules](#peering-rules). | No | +| `peering`       | Controls access to cluster peerings in the [Cluster Peering API](/consul/api-docs/peering). For more details, refer to [Peering Rules](#peering-rules). | No | | `namespace`
    `namespace_prefix` | Controls access to one or more namespaces.
    See [Namespace Rules](#namespace-rules) for details. | Yes | -| `node`
    `node_prefix`   | Controls access to node-level operations in the [Catalog API](/api-docs/catalog), [Health API](/api-docs/health), [Prepared Query API](/api-docs/query), [Network Coordinate API](/api-docs/coordinate), and [Agent API](/api-docs/agent)
    See [Node Rules](#node-rules) for details. | Yes | -| `operator`       | Controls access to cluster-level operations available in the [Operator API](/api-docs/operator) excluding keyring API endpoints.
    See [Operator Rules](#operator-rules) for details. | No | -| `query`
    `query_prefix` | Controls access to create, update, and delete prepared queries in the [Prepared Query API](/api-docs/query). Access to the [node](#node-rules) and [service](#service-rules) must also be granted.
    See [Prepared Query Rules](#prepared-query-rules) for details. | Yes | -| `service`
    `service_prefix` | Controls service-level operations in the [Catalog API](/api-docs/catalog), [Health API](/api-docs/health), [Intentions API](/api-docs/connect/intentions), [Prepared Query API](/api-docs/query), and [Agent API](/api-docs/agent).
    See [Service Rules](#service-rules) for details. | Yes | -| `session`
    `session_prefix` | Controls access to operations in the [Session API](/api-docs/session).
    See [Session Rules](#session-rules) for details. | Yes | +| `node`
    `node_prefix`   | Controls access to node-level operations in the [Catalog API](/consul/api-docs/catalog), [Health API](/consul/api-docs/health), [Prepared Query API](/consul/api-docs/query), [Network Coordinate API](/consul/api-docs/coordinate), and [Agent API](/consul/api-docs/agent)
    See [Node Rules](#node-rules) for details. | Yes | +| `operator`       | Controls access to cluster-level operations available in the [Operator API](/consul/api-docs/operator) excluding keyring API endpoints.
    See [Operator Rules](#operator-rules) for details. | No | +| `query`
    `query_prefix` | Controls access to create, update, and delete prepared queries in the [Prepared Query API](/consul/api-docs/query). Access to the [node](#node-rules) and [service](#service-rules) must also be granted.
    See [Prepared Query Rules](#prepared-query-rules) for details. | Yes | +| `service`
    `service_prefix` | Controls service-level operations in the [Catalog API](/consul/api-docs/catalog), [Health API](/consul/api-docs/health), [Intentions API](/consul/api-docs/connect/intentions), [Prepared Query API](/consul/api-docs/query), and [Agent API](/consul/api-docs/agent).
    See [Service Rules](#service-rules) for details. | Yes | +| `session`
    `session_prefix` | Controls access to operations in the [Session API](/consul/api-docs/session).
    See [Session Rules](#session-rules) for details. | Yes | The following resources are not covered by ACL policies: -- The [Status API](/api-docs/status) is used by servers when bootstrapping and exposes basic IP and port information about the servers, and does not allow modification of any state. -- The datacenter listing operation of the [Catalog API](/api-docs/catalog#list-datacenters) similarly exposes the names of known Consul datacenters, and does not allow modification of any state. -- The [connect CA roots endpoint](/api-docs/connect/ca#list-ca-root-certificates) exposes just the public TLS certificate which other systems can use to verify the TLS connection with Consul. +- The [Status API](/consul/api-docs/status) is used by servers when bootstrapping and exposes basic IP and port information about the servers, and does not allow modification of any state. +- The datacenter listing operation of the [Catalog API](/consul/api-docs/catalog#list-datacenters) similarly exposes the names of known Consul datacenters, and does not allow modification of any state. +- The [connect CA roots endpoint](/consul/api-docs/connect/ca#list-ca-root-certificates) exposes just the public TLS certificate which other systems can use to verify the TLS connection with Consul. --> **Consul Enterprise Namespace** - In addition to directly-linked policies, roles, and service identities, Consul Enterprise enables ACL policies and roles to be defined in the [Namespaces definition](/docs/enterprise/namespaces#namespace-definition) (Consul Enterprise 1.7.0+). +-> **Consul Enterprise Namespace** - In addition to directly-linked policies, roles, and service identities, Consul Enterprise enables ACL policies and roles to be defined in the [Namespaces definition](/consul/docs/enterprise/namespaces#namespace-definition) (Consul Enterprise 1.7.0+). The following topics provide additional details about the available resources. ## ACL Resource Rules -The `acl` resource controls access to ACL operations in the [ACL API](/api-docs/acl). Only one `acl` rule is allowed per policy. The value is set to one of the [policy dispositions](#policy-dispositions). +The `acl` resource controls access to ACL operations in the [ACL API](/consul/api-docs/acl). Only one `acl` rule is allowed per policy. The value is set to one of the [policy dispositions](#policy-dispositions). The `acl = "write"` rule is also required to create snapshots. This is because all token secrets are contained within the snapshot. @@ -158,7 +158,7 @@ partition_prefix "example-" { ## Agent Rules -The `agent` and `agent_prefix` resources control access to the utility operations in the [Agent API](/api-docs/agent), +The `agent` and `agent_prefix` resources control access to the utility operations in the [Agent API](/consul/api-docs/agent), such as join and leave. All of the catalog-related operations are covered by the [`node` or `node_prefix`](#node-rules) and [`service` or `service_prefix`](#service-rules) policies instead. @@ -201,14 +201,14 @@ allow read-write access to the node with the _exact_ name `foo`, read-only acces to any node name by using the empty prefix, and denies all access to any node name that starts with `bar`. -Since [Agent API](/api-docs/agent) utility operations may be required before an agent is joined to +Since [Agent API](/consul/api-docs/agent) utility operations may be required before an agent is joined to a cluster, or during an outage of the Consul servers or ACL datacenter, a special token may be -configured with [`acl.tokens.agent_recovery`](/docs/agent/config/config-files#acl_tokens_agent_recovery) to allow +configured with [`acl.tokens.agent_recovery`](/consul/docs/agent/config/config-files#acl_tokens_agent_recovery) to allow write access to these operations even if no ACL resolution capability is available. ## Event Rules -The `event` and `event_prefix` resources control access to event operations in the [Event API](/api-docs/event), such as +The `event` and `event_prefix` resources control access to event operations in the [Event API](/consul/api-docs/event), such as firing events and listing events. @@ -242,14 +242,14 @@ event "deploy" { Event rules are labeled with the event name they apply to. In the example above, the rules allow read-only access to any event, and firing of the "deploy" event. -The [`consul exec`](/commands/exec) command uses events with the "\_rexec" prefix during +The [`consul exec`](/consul/commands/exec) command uses events with the "\_rexec" prefix during operation, so to enable this feature in a Consul environment with ACLs enabled, you will need to give agents a token with access to this event prefix, in addition to configuring -[`disable_remote_exec`](/docs/agent/config/config-files#disable_remote_exec) to `false`. +[`disable_remote_exec`](/consul/docs/agent/config/config-files#disable_remote_exec) to `false`. ## Key/Value Rules -The `key` and `key_prefix` resources control access to key/value store operations in the [KV API](/api-docs/kv). +The `key` and `key_prefix` resources control access to key/value store operations in the [KV API](/consul/api-docs/kv). @@ -292,7 +292,7 @@ to any key name with the empty prefix rule, allow read-write access to the "foo" Enable the `list` policy disposition (Consul 1.0+) by setting the `acl.enable_key_list_policy` parameter to `true`. The disposition provides -recursive access to `key` entries. Refer to the [KV API](/api-docs/kv#recurse) +recursive access to `key` entries. Refer to the [KV API](/consul/api-docs/kv#recurse) documentation for additional information. In the following example, `key` resources that start with `bar` may be listed. @@ -353,11 +353,11 @@ EOF } ``` -For more detailed information, see the [Consul Sentinel documentation](/docs/agent/sentinel). +For more detailed information, see the [Consul Sentinel documentation](/consul/docs/agent/sentinel). ## Keyring Rules -The `keyring` resource controls access to keyring operations in the [Keyring API](/api-docs/operator/keyring). Only one keyring policy is allowed per rule set. The value is set to one of the policy dispositions, but may be read and updated. +The `keyring` resource controls access to keyring operations in the [Keyring API](/consul/api-docs/operator/keyring). Only one keyring policy is allowed per rule set. The value is set to one of the policy dispositions, but may be read and updated. @@ -526,9 +526,9 @@ specific namespace are prevented from accessing resources in another namespace. The `node` and `node_prefix` resources control access to the following API behaviors: -- node-level registration and read access to the [Catalog API](/api-docs/catalog) -- service discovery with the [Health API](/api-docs/health) -- filtering results in [Agent API](/api-docs/agent) operations, such as fetching the list of cluster members. +- node-level registration and read access to the [Catalog API](/consul/api-docs/catalog) +- service discovery with the [Health API](/consul/api-docs/health) +- filtering results in [Agent API](/consul/api-docs/agent) operations, such as fetching the list of cluster members. You can use resource labels to scope the rule to a specific resource or set of resources. @@ -573,25 +573,25 @@ node "admin" { Agents must be configured with `write` privileges for their own node name so that the agent can register their node metadata, tagged addresses, and other information in the catalog. If configured incorrectly, the agent will print an error to the console when it tries to sync its state with the catalog. -Configure `write` access in the [`acl.tokens.agent`](/docs/agent/config/config-files#acl_tokens_agent) parameter. +Configure `write` access in the [`acl.tokens.agent`](/consul/docs/agent/config/config-files#acl_tokens_agent) parameter. -The [`acl.token.default`](/docs/agent/config/config-files#acl_tokens_default) used by the agent should have `read` access to a given node so that the DNS interface can be queried. +The [`acl.token.default`](/consul/docs/agent/config/config-files#acl_tokens_default) used by the agent should have `read` access to a given node so that the DNS interface can be queried. Node rules are used to filter query results when reading from the catalog or retrieving information from the health endpoints. This allows for configurations where a token has access to a given service name, but only on an allowed subset of node names. -Consul agents check tokens locally when health checks are registered and when Consul performs periodic [anti-entropy](/docs/architecture/anti-entropy) syncs. +Consul agents check tokens locally when health checks are registered and when Consul performs periodic [anti-entropy](/consul/docs/architecture/anti-entropy) syncs. These actions may required an ACL token to complete. Use the following methods to configure ACL tokens for registration events: -* Configure a global token in the [acl.tokens.default](/docs/agent/config/config-files#acl_tokens_default) parameter. +* Configure a global token in the [acl.tokens.default](/consul/docs/agent/config/config-files#acl_tokens_default) parameter. This allows a single token to be used during all check registration operations. * Provide an ACL token with `service` and `check` definitions at registration time. This allows for greater flexibility and enables the use of multiple tokens on the same agent. - Refer to the [services](/docs/discovery/services) and [checks](/docs/discovery/checks) documentation for examples. - Tokens may also be passed to the [HTTP API](/api-docs) for operations that require them. + Refer to the [services](/consul/docs/discovery/services) and [checks](/consul/docs/discovery/checks) documentation for examples. + Tokens may also be passed to the [HTTP API](/consul/api-docs) for operations that require them. ### Reading Imported Nodes -Nodes rules affect read access to nodes with services exported by [`exported-services` configuration entries](/docs/connect/config-entries/exported-services#reading-services), including nodes imported from [cluster peerings](/docs/connect/cluster-peering) or [admin partitions](/docs/enterprise/admin-partitions) (Enterprise-only). +Nodes rules affect read access to nodes with services exported by [`exported-services` configuration entries](/consul/docs/connect/config-entries/exported-services#reading-services), including nodes imported from [cluster peerings](/consul/docs/connect/cluster-peering) or [admin partitions](/consul/docs/enterprise/admin-partitions) (Enterprise-only). Read access to all imported nodes is granted when either of the following rule sets are attached to a token: - `service:write` is granted to any service. - `node:read` is granted to all nodes. @@ -599,14 +599,14 @@ Read access to all imported nodes is granted when either of the following rule s For Consul Enterprise, either set of rules must be scoped to the requesting services's partition and at least one namespace. You may need similarly scoped [Service Rules](#reading-imported-services) to read Consul data, depending on the endpoint (e.g. `/v1/health/service/:name`). -These permissions are satisfied when using a [service identity](/docs/security/acl/acl-roles#service-identities). +These permissions are satisfied when using a [service identity](/consul/docs/security/acl/acl-roles#service-identities). -Refer to [Reading Services](/docs/connect/config-entries/exported-services#reading-services) for example ACL policies used to read imported services using the health endpoint. +Refer to [Reading Services](/consul/docs/connect/config-entries/exported-services#reading-services) for example ACL policies used to read imported services using the health endpoint. ## Operator Rules The `operator` resource controls access to cluster-level operations in the -[Operator API](/api-docs/operator), other than the [Keyring API](/api-docs/operator/keyring). +[Operator API](/consul/api-docs/operator), other than the [Keyring API](/consul/api-docs/operator/keyring). Only one operator rule allowed per rule set. In the following example, the token may be used to query the operator endpoints for diagnostic purposes but it will not make changes. @@ -626,7 +626,7 @@ operator = "read" ## Peering Rules -The `peering` resource controls access to cluster peerings in the [Cluster Peering API](/api-docs/peering). +The `peering` resource controls access to cluster peerings in the [Cluster Peering API](/consul/api-docs/peering). In Consul Enterprise, peering rules are scoped to an admin partition. Therefore, they can be nested in an [admin partition rule](#admin-partition-rules) but not a [namespace rule](#namespace-rules). @@ -652,7 +652,7 @@ For an example of how to apply rules for the `peering` resource alongside other ## Prepared Query Rules The `query` and `query_prefix` resources control access to create, update, and delete prepared queries in the -[Prepared Query API](/api-docs/query). Specify the resource label in query rules to determine the scope of the rule. +[Prepared Query API](/consul/api-docs/query). Specify the resource label in query rules to determine the scope of the rule. The resource label in the following example is empty. As a result, the rules allow read-only access to query resources with any name. The rules also grant read-write access to the query named `foo`, which allows control of the query namespace to be delegated based on ACLs: @@ -710,7 +710,7 @@ here, with examples: that is used and known by many clients to provide geo-failover behavior for a database. -- [Template queries](/api-docs/query#prepared-query-templates) +- [Template queries](/consul/api-docs/query#prepared-query-templates) queries work like static queries with a `Name` defined, except that a catch-all template with an empty `Name` requires an ACL token that can write to any query prefix. @@ -757,7 +757,7 @@ These differences are outlined in the table below: ## Service Rules -The `service` and `service_prefix` resources control service-level registration and read access to the [Catalog API](/api-docs/catalog) and service discovery with the [Health API](/api-docs/health). +The `service` and `service_prefix` resources control service-level registration and read access to the [Catalog API](/consul/api-docs/catalog) and service discovery with the [Health API](/consul/api-docs/health). Specify the resource label in service rules to set the scope of the rule. The resource label in the following example is empty. As a result, the rules allow read-only access to any service name with the empty prefix. The rules also allow read-write access to the `app` service and deny all access to the `admin` service: @@ -797,40 +797,40 @@ service "admin" { Consul's DNS interface is affected by restrictions on service rules. If the -[`acl.tokens.default`](/docs/agent/config/config-files#acl_tokens_default) used by the agent does not have `read` access to a +[`acl.tokens.default`](/consul/docs/agent/config/config-files#acl_tokens_default) used by the agent does not have `read` access to a given service, then the DNS interface will return no records when queried for it. When reading from the catalog or retrieving information from the health endpoints, service rules are used to filter the results of the query. -Service rules come into play when using the [Agent API](/api-docs/agent) to register services or +Service rules come into play when using the [Agent API](/consul/api-docs/agent) to register services or checks. The agent will check tokens locally as a service or check is registered, and Consul also -performs periodic [anti-entropy](/docs/architecture/anti-entropy) syncs, which may require an +performs periodic [anti-entropy](/consul/docs/architecture/anti-entropy) syncs, which may require an ACL token to complete. To accommodate this, Consul provides two methods of configuring ACL tokens to use for registration events: -1. Using the [acl.tokens.default](/docs/agent/config/config-files#acl_tokens_default) configuration +1. Using the [acl.tokens.default](/consul/docs/agent/config/config-files#acl_tokens_default) configuration directive. This allows a single token to be configured globally and used during all service and check registration operations. 2. Providing an ACL token with service and check definitions at registration time. This allows for greater flexibility and enables the use of multiple tokens on the same agent. Examples of what this looks like are available for - both [services](/docs/discovery/services) and - [checks](/docs/discovery/checks). Tokens may also be passed to the [HTTP - API](/api-docs) for operations that require them. **Note:** all tokens + both [services](/consul/docs/discovery/services) and + [checks](/consul/docs/discovery/checks). Tokens may also be passed to the [HTTP + API](/consul/api-docs) for operations that require them. **Note:** all tokens passed to an agent are persisted on local disk to allow recovery from restarts. See [`-data-dir` flag - documentation](/docs/agent/config/cli-flags#_data_dir) for notes on securing + documentation](/consul/docs/agent/config/cli-flags#_data_dir) for notes on securing access. In addition to ACLs, in Consul 0.9.0 and later, the agent must be configured with -[`enable_script_checks`](/docs/agent/config/config-files#enable_script_checks) or -[`enable_local_script_checks`](/docs/agent/config/config-files#enable_local_script_checks) +[`enable_script_checks`](/consul/docs/agent/config/config-files#enable_script_checks) or +[`enable_local_script_checks`](/consul/docs/agent/config/config-files#enable_local_script_checks) set to `true` in order to enable script checks. ### Reading Imported Services -Service rules affect read access to services exported by [`exported-services` configuration entries](/docs/connect/config-entries/exported-services#reading-services), including services exported between [cluster peerings](/docs/connect/cluster-peering) or [admin partitions](/docs/enterprise/admin-partitions) (Enterprise-only). +Service rules affect read access to services exported by [`exported-services` configuration entries](/consul/docs/connect/config-entries/exported-services#reading-services), including services exported between [cluster peerings](/consul/docs/connect/cluster-peering) or [admin partitions](/consul/docs/enterprise/admin-partitions) (Enterprise-only). Read access to all imported services is granted when either of the following rule sets are attached to a token: - `service:write` is granted to any service. - `service:read` is granted to all services. @@ -838,9 +838,9 @@ Read access to all imported services is granted when either of the following rul For Consul Enterprise, either set of rules must be scoped to the requesting services's partition and at least one namespace. You may need similarly scoped [Node Rules](#reading-imported-nodes) to read Consul data, depending on the endpoint (e.g. `/v1/health/service/:name`). -These permissions are satisfied when using a [service identity](/docs/security/acl/acl-roles#service-identities). +These permissions are satisfied when using a [service identity](/consul/docs/security/acl/acl-roles#service-identities). -Refer to [Reading Services](/docs/connect/config-entries/exported-services#reading-services) for example ACL policies used to read imported services using the health endpoint. +Refer to [Reading Services](/consul/docs/connect/config-entries/exported-services#reading-services) for example ACL policies used to read imported services using the health endpoint. ### Intentions @@ -870,12 +870,12 @@ service "app" { -Refer to [Intention Management Permissions](/docs/connect/intentions#intention-management-permissions) +Refer to [Intention Management Permissions](/consul/docs/connect/intentions#intention-management-permissions) for more information about managing intentions access with service rules. ## Session Rules -The `session` and `session_prefix` resources controls access to [Session API](/api-docs/session) operations. +The `session` and `session_prefix` resources controls access to [Session API](/consul/api-docs/session) operations. Specify the resource label in session rules to set the scope of the rule. The resource label in the following example is empty. As a result, the rules allow read-only access to all sessions. diff --git a/website/content/docs/security/acl/acl-tokens.mdx b/website/content/docs/security/acl/acl-tokens.mdx index d93da8d72b..bb239e1a8a 100644 --- a/website/content/docs/security/acl/acl-tokens.mdx +++ b/website/content/docs/security/acl/acl-tokens.mdx @@ -13,15 +13,15 @@ This topic describes access control list (ACL) tokens, which are the core method Tokens are artifacts in the ACL system used to authenticate users, services, and Consul agents. When ACLs are enabled, entities requesting access to a resource must include a token that has been linked with a policy, service identity, or node identity that grants permission to the resource. The ACL system checks the token and grants or denies access to resource based on the associated permissions. -Refer to the [ACL system workflow overview](/docs/security/acl#workflow-overview) for information about tokens' role in the ACL system. +Refer to the [ACL system workflow overview](/consul/docs/security/acl#workflow-overview) for information about tokens' role in the ACL system. ## Creating Tokens The person responsible for administrating ACLs can use the API or CLI to create and link tokens to entities that enable permissions to resources. -Refer to the [ACL API](/api-docs/acl) and [ACL CLI](/commands/acl) documentation for instructions on how to create and link tokens. Tokens can also be created dynamically from trusted external system using an -[auth method](/docs/security/acl/auth-methods). +Refer to the [ACL API](/consul/api-docs/acl) and [ACL CLI](/consul/commands/acl) documentation for instructions on how to create and link tokens. Tokens can also be created dynamically from trusted external system using an +[auth method](/consul/docs/security/acl/auth-methods). -Refer to the [Secure Consul with Access Control Lists (ACLs)](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production?in=consul/security) tutorial for help getting started with creating tokens. The tutorial includes an interactive sandbox so that you can perform the procedures without configuring your local environment. +Refer to the [Secure Consul with Access Control Lists (ACLs)](/consul/tutorials/security/access-control-setup-production) tutorial for help getting started with creating tokens. The tutorial includes an interactive sandbox so that you can perform the procedures without configuring your local environment. ## Passing Tokens @@ -66,20 +66,20 @@ service = { -Refer to the [service definitions documentation](/docs/discovery/services#service-definition) for additional information. +Refer to the [service definitions documentation](/consul/docs/discovery/services#service-definition) for additional information. ### Agent Requests -Consul agents can be configured to hold several ACL tokens (see [`tokens`](/docs/agent/config/config-files#acl_tokens_default)) to accommodate several use cases. The following table describes agent configuration fields where ACLs are applicable and whether the configurations apply to servers, clients, or both. +Consul agents can be configured to hold several ACL tokens (see [`tokens`](/consul/docs/agent/config/config-files#acl_tokens_default)) to accommodate several use cases. The following table describes agent configuration fields where ACLs are applicable and whether the configurations apply to servers, clients, or both. | Configuration Option | Servers | Clients | Purpose | | -------------------------------------------------------------- | ---------- | ---------- | ---------------------------------------------------------------------- | -| [`acl.enabled`](/docs/agent/config/config-files#acl_enabled) | `REQUIRED` | `REQUIRED` | Controls whether ACLs are enabled | -| [`acl.default_policy`](/docs/agent/config/config-files#acl_default_policy) | `OPTIONAL` | `N/A` | Determines allowlist or denylist mode | -| [`acl.down_policy`](/docs/agent/config/config-files#acl_down_policy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the remote token or policy resolution fails | -| [`acl.role_ttl`](/docs/agent/config/config-files#acl_role_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Roles | -| [`acl.policy_ttl`](/docs/agent/config/config-files#acl_policy_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Policies | -| [`acl.token_ttl`](/docs/agent/config/config-files#acl_token_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Tokens | +| [`acl.enabled`](/consul/docs/agent/config/config-files#acl_enabled) | `REQUIRED` | `REQUIRED` | Controls whether ACLs are enabled | +| [`acl.default_policy`](/consul/docs/agent/config/config-files#acl_default_policy) | `OPTIONAL` | `N/A` | Determines allowlist or denylist mode | +| [`acl.down_policy`](/consul/docs/agent/config/config-files#acl_down_policy) | `OPTIONAL` | `OPTIONAL` | Determines what to do when the remote token or policy resolution fails | +| [`acl.role_ttl`](/consul/docs/agent/config/config-files#acl_role_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Roles | +| [`acl.policy_ttl`](/consul/docs/agent/config/config-files#acl_policy_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Policies | +| [`acl.token_ttl`](/consul/docs/agent/config/config-files#acl_token_ttl) | `OPTIONAL` | `OPTIONAL` | Determines time-to-live for cached ACL Tokens | In the following example, the agent is configured to use a default token: @@ -101,11 +101,11 @@ tokens = { -Refer to the [agent configurations documentation](/docs/agent/config/config-files) for additional information. +Refer to the [agent configurations documentation](/consul/docs/agent/config/config-files) for additional information. ### Command Line Requests -To make a request on the command line, specify the ACL token with the [`-token` command line flag](/commands#authentication). +To make a request on the command line, specify the ACL token with the [`-token` command line flag](/consul/commands#authentication). In the following example, a token is included to enable the user to create an intention on the command line: ```shell-session @@ -116,11 +116,11 @@ Refer to the documentation for the command line operations you want to perform f #### Environment Variables -You can export tokens to environment variables on the local machine, which enable you to omit the `-token` flag when performing operations on the Consul command line. Refer to the [Consul command line documentation](/commands#environment-variables) for details. +You can export tokens to environment variables on the local machine, which enable you to omit the `-token` flag when performing operations on the Consul command line. Refer to the [Consul command line documentation](/consul/commands#environment-variables) for details. ### API Requests -Specify the token in the HTTP `X-Consul-Token` header field to make an API request. Refer to the [HTTP API documentation](/api-docs/api-structure#authentication) for details. +Specify the token in the HTTP `X-Consul-Token` header field to make an API request. Refer to the [HTTP API documentation](/consul/api-docs/api-structure#authentication) for details. The following example shows the header for a GET request to the `agent/members` endpoint. @@ -131,18 +131,18 @@ $ curl --header "X-Consul-Token: " "http://127.0.0.1:8500/v1/agent/member ## Token Attributes The following table is a partial list of attributes that a token may contain. -Refer to the [API](/api-docs/acl/tokens) or [command line](/commands/acl/token) documentation for all attributes that can be assigned or generated for a token: +Refer to the [API](/consul/api-docs/acl/tokens) or [command line](/consul/commands/acl/token) documentation for all attributes that can be assigned or generated for a token: | Attribute | Description | Type | Default | | ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------------- | -| `AccessorID` | Used for [audit logging](/docs/enterprise/audit-logging). The accessor ID is also returned in API responses to identify the token without revealing the secret ID. | String | auto-generated | +| `AccessorID` | Used for [audit logging](/consul/docs/enterprise/audit-logging). The accessor ID is also returned in API responses to identify the token without revealing the secret ID. | String | auto-generated | | `SecretID` | Used to request access to resources, data, and APIs. | String | auto-generated | -| `Partition` | Specifies the name of the admin partition in which the token is valid. See [Admin Partitions](/docs/enterprise/admin-partitions) for additional information. | String | `default` | -| `Namespace` | Specifies the name of the Consul namespace in which the token is valid. See [Namespaces](/docs/enterprise/namespaces) for additional information. | String | `default` | +| `Partition` | Specifies the name of the admin partition in which the token is valid. See [Admin Partitions](/consul/docs/enterprise/admin-partitions) for additional information. | String | `default` | +| `Namespace` | Specifies the name of the Consul namespace in which the token is valid. See [Namespaces](/consul/docs/enterprise/namespaces) for additional information. | String | `default` | | `Description` | Human-readable description for documenting the purpose of the token. | String | none | | `Local` | Indicates whether the token should be replicated globally or local to the datacenter.
    Set to `false` to replicate globally across all reachable datacenters.
    Setting to `true` configures the token to functional in the local datacenter only. | Boolean | `false` | -| `ServiceIdentities` | Specifies a list of service identities to apply to the token. See [Service Identities](/docs/security/acl/acl-roles#service-identities) in the "Roles" topic for additional information. | Array | none | -| `NodeIdentities` | Specifies a list of node identities to apply to the token. See [Node Identities](/docs/security/acl/acl-roles#node-identities) in the "Roles" topic for additional information. | Array | none | +| `ServiceIdentities` | Specifies a list of service identities to apply to the token. See [Service Identities](/consul/docs/security/acl/acl-roles#service-identities) in the "Roles" topic for additional information. | Array | none | +| `NodeIdentities` | Specifies a list of node identities to apply to the token. See [Node Identities](/consul/docs/security/acl/acl-roles#node-identities) in the "Roles" topic for additional information. | Array | none | | `Legacy` | Indicates if the token was created using the the legacy ACL system. | Boolean | `false` | | `Policies` | List of policies linked to the token, including the policy ID and name. | String | none | | `Roles` | List of roles linked to the token, including the role ID and name. | String | none | @@ -154,24 +154,24 @@ system or accessing Consul under specific conditions. The following table descri | Token | Servers | Clients | Description | | ------------------------------------------------------------------------------------ | ---------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| [`acl.tokens.agent_recovery`](/docs/agent/config/config-files#acl_tokens_agent_recovery) | `OPTIONAL` | `OPTIONAL` | Enables access to the [Agent API](/api-docs/agent) when remote bearer token resolution fails.
    Used for setting up the cluster and performing initial join operations.
    See [ACL Agent Recovery Token](#acl-agent-recovery-token) for details. | -| [`acl.tokens.agent`](/docs/agent/config/config-files#acl_tokens_agent) | `OPTIONAL` | `OPTIONAL` | Used for internal agent operations. See [ACL Agent Token](#acl-agent-token) for details. | -| [`acl.tokens.initial_management`](/docs/agent/config/config-files#acl_tokens_initial_management) | `OPTIONAL` | `N/A` | Used to bootstrap the ACL system. See [Initial Management Token](#initial-management-token). | -| [`acl.tokens.default`](/docs/agent/config/config-files#acl_tokens_default) | `OPTIONAL` | `OPTIONAL` | Specifies a default token to use for client requests if no token is supplied. This is commonly configured with read-only access to services to enable DNS service discovery on agents. | +| [`acl.tokens.agent_recovery`](/consul/docs/agent/config/config-files#acl_tokens_agent_recovery) | `OPTIONAL` | `OPTIONAL` | Enables access to the [Agent API](/consul/api-docs/agent) when remote bearer token resolution fails.
    Used for setting up the cluster and performing initial join operations.
    See [ACL Agent Recovery Token](#acl-agent-recovery-token) for details. | +| [`acl.tokens.agent`](/consul/docs/agent/config/config-files#acl_tokens_agent) | `OPTIONAL` | `OPTIONAL` | Used for internal agent operations. See [ACL Agent Token](#acl-agent-token) for details. | +| [`acl.tokens.initial_management`](/consul/docs/agent/config/config-files#acl_tokens_initial_management) | `OPTIONAL` | `N/A` | Used to bootstrap the ACL system. See [Initial Management Token](#initial-management-token). | +| [`acl.tokens.default`](/consul/docs/agent/config/config-files#acl_tokens_default) | `OPTIONAL` | `OPTIONAL` | Specifies a default token to use for client requests if no token is supplied. This is commonly configured with read-only access to services to enable DNS service discovery on agents. | -All reserved tokens except the `initial_management` token can be created or updated using the [/v1/agent/token API](/api-docs/agent#update-acl-tokens). +All reserved tokens except the `initial_management` token can be created or updated using the [/v1/agent/token API](/consul/api-docs/agent#update-acl-tokens). ### Snapshot Tokens -Snapshots are artifacts created with the [snapshot API](/api-docs/snapshot) for backup and recovery purposes. Snapshots contain ACL tokens and interacting with them requires a token with `acl:write` privileges. +Snapshots are artifacts created with the [snapshot API](/consul/api-docs/snapshot) for backup and recovery purposes. Snapshots contain ACL tokens and interacting with them requires a token with `acl:write` privileges. ### ACL Agent Token -The [`acl.tokens.agent`](/docs/agent/config/config-files#acl_tokens_agent) is a special token that is used for an agent's internal operations. It isn't used directly for any user-initiated operations like the [`acl.tokens.default`](/docs/agent/config/config-files#acl_tokens_default), though if the `acl.tokens.agent` isn't configured the `acl.tokens.default` will be used. The ACL agent token is used for the following operations by the agent: +The [`acl.tokens.agent`](/consul/docs/agent/config/config-files#acl_tokens_agent) is a special token that is used for an agent's internal operations. It isn't used directly for any user-initiated operations like the [`acl.tokens.default`](/consul/docs/agent/config/config-files#acl_tokens_default), though if the `acl.tokens.agent` isn't configured the `acl.tokens.default` will be used. The ACL agent token is used for the following operations by the agent: -1. Updating the agent's node entry using the [Catalog API](/api-docs/catalog), including updating its node metadata, tagged addresses, and network coordinates -2. Performing [anti-entropy](/docs/architecture/anti-entropy) syncing, in particular reading the node metadata and services registered with the catalog -3. Reading and writing the special `_rexec` section of the KV store when executing [`consul exec`](/commands/exec) commands +1. Updating the agent's node entry using the [Catalog API](/consul/api-docs/catalog), including updating its node metadata, tagged addresses, and network coordinates +2. Performing [anti-entropy](/consul/docs/architecture/anti-entropy) syncing, in particular reading the node metadata and services registered with the catalog +3. Reading and writing the special `_rexec` section of the KV store when executing [`consul exec`](/consul/commands/exec) commands Here's an example policy sufficient to accomplish the above for a node called `mynode`: @@ -191,7 +191,7 @@ key_prefix "_rexec" {     -The `service_prefix` policy needs read access for any services that can be registered on the agent. If [remote exec is disabled](/docs/agent/config/config-files#disable_remote_exec), the default, then the `key_prefix` policy can be omitted. +The `service_prefix` policy needs read access for any services that can be registered on the agent. If [remote exec is disabled](/consul/docs/agent/config/config-files#disable_remote_exec), the default, then the `key_prefix` policy can be omitted. ## Built-in Tokens @@ -210,11 +210,11 @@ The description and policies may be updated, but the anonymous token cannot be d ### Initial Management Token Including an initial management token in the Consul configuration creates the -token and links it with the built-in [global management](/docs/security/acl/acl-policies#global-management) policy. +token and links it with the built-in [global management](/consul/docs/security/acl/acl-policies#global-management) policy. The bearer will have have unrestricted privileges to resources and APIs. The `SecretID` attribute will be set to the value of the configuration entry. -See the [Bootstrapping ACLs tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) for guidance on bootstrapping. +See the [Bootstrapping ACLs tutorial](/consul/tutorials/security/access-control-setup-production) for guidance on bootstrapping. **Note:** Raft Protocol is versioned separately, but maintains compatibility with at least one prior version. See [here](/docs/upgrading/upgrade-specific#raft-protocol-version-compatibility) for details. +-> **Note:** Raft Protocol is versioned separately, but maintains compatibility with at least one prior version. See [here](/consul/docs/upgrading/upgrade-specific#raft-protocol-version-compatibility) for details. diff --git a/website/content/docs/upgrading/index.mdx b/website/content/docs/upgrading/index.mdx index e9a2a892c9..27500a4cb4 100644 --- a/website/content/docs/upgrading/index.mdx +++ b/website/content/docs/upgrading/index.mdx @@ -17,7 +17,7 @@ keep in mind when using Consul. This page documents how to upgrade Consul when a new version is released. --> **Tip:** For Consul Enterprise, see the [Automated Upgrades documentation](/docs/enterprise/upgrades). +-> **Tip:** For Consul Enterprise, see the [Automated Upgrades documentation](/consul/docs/enterprise/upgrades). ## Standard Upgrades @@ -25,12 +25,12 @@ For upgrades we strive to ensure backwards compatibility. To support this, nodes gossip their protocol version and builds. This enables clients and servers to intelligently enable new features when available, or to gracefully fallback to a backward compatible mode of operation otherwise. -Visit the [General Upgrade Process](/docs/upgrading/instructions/general-process) for a detailed upgrade guide. +Visit the [General Upgrade Process](/consul/docs/upgrading/instructions/general-process) for a detailed upgrade guide. For most upgrades, the process is simple. Assuming the current version of Consul is A, and version B is released. -1. Check the [version's upgrade notes](/docs/upgrading/upgrade-specific) to ensure +1. Check the [version's upgrade notes](/consul/docs/upgrading/upgrade-specific) to ensure there are no compatibility issues that will affect your workload. If there are plan accordingly before continuing. @@ -44,7 +44,7 @@ Consul is A, and version B is released. the same process. -> **Upgrade Envoy proxies:** If a client agent has associated Envoy proxies (e.g., sidecars, gateways), - install a [compatible Envoy version](/docs/connect/proxies/envoy#supported-versions) + install a [compatible Envoy version](/consul/docs/connect/proxies/envoy#supported-versions) for Consul version B. After stopping client agent version A, stop its associated Envoy proxies. @@ -62,7 +62,7 @@ version can increase the risk incurred during upgrades. We encourage our users t remain no more than two major versions behind (i.e., if 1.8.x is the current release, do not use versions older than 1.6.x). If you find yourself in a situation where you are many major versions behind, and need to upgrade, please review our -[Upgrade Instructions page](/docs/upgrading/instructions) for information on +[Upgrade Instructions page](/consul/docs/upgrading/instructions) for information on how to perform those upgrades. ## Backward Incompatible Upgrades @@ -89,7 +89,7 @@ version B comes out. You can verify this is the case by running `consul members` to make sure all members are speaking the same, latest protocol version. -The key to making this work is the [protocol compatibility](/docs/upgrading/compatibility) +The key to making this work is the [protocol compatibility](/consul/docs/upgrading/compatibility) of Consul. The protocol version system is discussed below. ## Protocol Versions @@ -132,10 +132,10 @@ your cluster so that you can run the latest protocol version. ## Upgrading on Kubernetes -See the dedicated [Upgrading Consul on Kubernetes](/docs/k8s/upgrade) page. +See the dedicated [Upgrading Consul on Kubernetes](/consul/docs/k8s/upgrade) page. ## Upgrading federated datacenters If you need to upgrade a federated environment with multiple datacenters you can -refer to the [Upgrade Multiple Federated Consul Datacenters](https://learn.hashicorp.com/tutorials/consul/upgrade-federated-environment) +refer to the [Upgrade Multiple Federated Consul Datacenters](/consul/tutorials/datacenter-operations/upgrade-federated-environment) tutorial. diff --git a/website/content/docs/upgrading/instructions/general-process.mdx b/website/content/docs/upgrading/instructions/general-process.mdx index f3339b5d0e..373256cc54 100644 --- a/website/content/docs/upgrading/instructions/general-process.mdx +++ b/website/content/docs/upgrading/instructions/general-process.mdx @@ -12,7 +12,7 @@ description: >- This document describes some best practices that you should follow when upgrading Consul. Some versions also have steps that are specific to that -version, so make sure you also review the [upgrade instructions](/docs/upgrading/instructions) +version, so make sure you also review the [upgrade instructions](/consul/docs/upgrading/instructions) for the version you are on. ## Download the New Version @@ -39,7 +39,7 @@ Docker containers are available at these locations: If you are using Kubernetes, then please review our documentation for -[Upgrading Consul on Kubernetes](/docs/k8s/upgrade). +[Upgrading Consul on Kubernetes](/consul/docs/k8s/upgrade).     @@ -71,10 +71,10 @@ Version 1 This will ensure you have a safe fallback option in case something goes wrong. Store this snapshot somewhere safe. More documentation on snapshot usage is available here: -- [consul.io/commands/snapshot](/commands/snapshot) -- [Backup Consul Data and State tutorial](https://learn.hashicorp.com/tutorials/consul/backup-and-restore) +- [consul.io/commands/snapshot](/consul/commands/snapshot) +- [Backup Consul Data and State tutorial](/consul/tutorials/production-deploy/backup-and-restore) -**2.** Temporarily modify your Consul configuration so that its [log_level](/docs/agent/config/cli-flags#_log_level) +**2.** Temporarily modify your Consul configuration so that its [log_level](/consul/docs/agent/config/cli-flags#_log_level) is set to `debug`. After doing this, issue the following command on your servers to reload the configuration: @@ -173,7 +173,7 @@ all of your servers attempting to kick off leadership elections endlessly withou reaching a quorum and electing a leader. Most of these problems can be solved by following the steps outlined in our -[Outage Recovery](https://learn.hashicorp.com/tutorials/consul/recovery-outage) document. +[Outage Recovery](/consul/tutorials/datacenter-operations/recovery-outage) document. If you are still having trouble after trying the recovery steps outlined there, then the following options for further assistance are available: @@ -183,7 +183,7 @@ then the following options for further assistance are available: When contacting Hashicorp Support, please include the following information in your ticket: - Consul version you were upgrading FROM and TO. -- [Debug level logs](/docs/agent/config/cli-flags#_log_level) from all servers in the cluster +- [Debug level logs](/consul/docs/agent/config/cli-flags#_log_level) from all servers in the cluster that you are having trouble with. These should include logs from prior to the upgrade attempt up through the current time. If your logs were not set at debug level prior to the upgrade, please include those logs as well. Also, update your config to use debug logs, diff --git a/website/content/docs/upgrading/instructions/index.mdx b/website/content/docs/upgrading/instructions/index.mdx index c0d869ba38..8c2b3c0805 100644 --- a/website/content/docs/upgrading/instructions/index.mdx +++ b/website/content/docs/upgrading/instructions/index.mdx @@ -20,7 +20,7 @@ Our recommended upgrade path is to move through the following sequence of versio - 1.8.19 (final 1.8.x) - 1.10.12 (final 1.10.x) - Latest 1.12.x -- Latest 1.13.x ([at least 1.13.1](/docs/upgrading/upgrade-specific#service-mesh-compatibility)) +- Latest 1.13.x ([at least 1.13.1](/consul/docs/upgrading/upgrade-specific#service-mesh-compatibility)) - Latest 1.14.x ## Getting Started @@ -32,22 +32,22 @@ we recommend reviewing the changelog for versions between the one you are on and one you are upgrading to at each step to familiarize yourself with changes. Select your _currently installed_ release series: -- 1.13.x: work upwards from [1.14 upgrade notes](/docs/upgrading/upgrade-specific#consul-1-14-x) -- 1.12.x: work upwards from [1.13 upgrade notes](/docs/upgrading/upgrade-specific#consul-1-13-x) -- 1.11.x: work upwards from [1.12 upgrade notes](/docs/upgrading/upgrade-specific#consul-1-12-0) -- 1.10.x: work upwards from [1.11 upgrade notes](/docs/upgrading/upgrade-specific#consul-1-11-0) -- [1.9.x](/docs/upgrading/instructions/upgrade-to-1-10-x) -- [1.8.x](/docs/upgrading/instructions/upgrade-to-1-10-x) -- [1.7.x](/docs/upgrading/instructions/upgrade-to-1-8-x) -- [1.6.x](/docs/upgrading/instructions/upgrade-to-1-8-x) -- [1.5.x](/docs/upgrading/instructions/upgrade-to-1-6-x) -- [1.4.x](/docs/upgrading/instructions/upgrade-to-1-6-x) -- [1.3.x](/docs/upgrading/instructions/upgrade-to-1-6-x) -- [1.2.x](/docs/upgrading/instructions/upgrade-to-1-6-x) -- [1.1.x](/docs/upgrading/instructions/upgrade-to-1-2-x) -- [1.0.x](/docs/upgrading/instructions/upgrade-to-1-2-x) -- [0.9.x](/docs/upgrading/instructions/upgrade-to-1-2-x) -- [0.8.x](/docs/upgrading/instructions/upgrade-to-1-2-x) +- 1.13.x: work upwards from [1.14 upgrade notes](/consul/docs/upgrading/upgrade-specific#consul-1-14-x) +- 1.12.x: work upwards from [1.13 upgrade notes](/consul/docs/upgrading/upgrade-specific#consul-1-13-x) +- 1.11.x: work upwards from [1.12 upgrade notes](/consul/docs/upgrading/upgrade-specific#consul-1-12-0) +- 1.10.x: work upwards from [1.11 upgrade notes](/consul/docs/upgrading/upgrade-specific#consul-1-11-0) +- [1.9.x](/consul/docs/upgrading/instructions/upgrade-to-1-10-x) +- [1.8.x](/consul/docs/upgrading/instructions/upgrade-to-1-10-x) +- [1.7.x](/consul/docs/upgrading/instructions/upgrade-to-1-8-x) +- [1.6.x](/consul/docs/upgrading/instructions/upgrade-to-1-8-x) +- [1.5.x](/consul/docs/upgrading/instructions/upgrade-to-1-6-x) +- [1.4.x](/consul/docs/upgrading/instructions/upgrade-to-1-6-x) +- [1.3.x](/consul/docs/upgrading/instructions/upgrade-to-1-6-x) +- [1.2.x](/consul/docs/upgrading/instructions/upgrade-to-1-6-x) +- [1.1.x](/consul/docs/upgrading/instructions/upgrade-to-1-2-x) +- [1.0.x](/consul/docs/upgrading/instructions/upgrade-to-1-2-x) +- [0.9.x](/consul/docs/upgrading/instructions/upgrade-to-1-2-x) +- [0.8.x](/consul/docs/upgrading/instructions/upgrade-to-1-2-x) If you are using <= 0.7.x, please contact support for assistance: - OSS users without paid support plans can request help in our [Community Forum](https://discuss.hashicorp.com/c/consul/29) diff --git a/website/content/docs/upgrading/instructions/upgrade-to-1-10-x.mdx b/website/content/docs/upgrading/instructions/upgrade-to-1-10-x.mdx index 8fef8ab259..0610b95c05 100644 --- a/website/content/docs/upgrading/instructions/upgrade-to-1-10-x.mdx +++ b/website/content/docs/upgrading/instructions/upgrade-to-1-10-x.mdx @@ -12,7 +12,7 @@ description: >- This guide explains how to best upgrade a single Consul Enterprise datacenter to latest v1.10.x from a version of Consul that is forward compatible with v1.10. If you are on a major -version of Consul prior to 1.8, you must first [upgrade to latest 1.8.x](/docs/upgrading/instructions/upgrade-to-1-8-x) +version of Consul prior to 1.8, you must first [upgrade to latest 1.8.x](/consul/docs/upgrading/instructions/upgrade-to-1-8-x) before continuing with this guide. If you are already on a major version of 1.8 or 1.9, then this guide will go over the procedures required for upgrading to v1.10.x. This process will require intermediate version upgrades to a forward-compatible release of v1.8 or v1.9, @@ -20,32 +20,32 @@ as well as other licensing related configuration changes. If you have multiple C upgrade them in the normal order and take the following instructions into account for each upgrade. For the open source version of Consul please follow the -[General Upgrade Process](/docs/upgrading/instructions/general-process). +[General Upgrade Process](/consul/docs/upgrading/instructions/general-process). ~> You can only upgrade to Consul Enterprise 1.10 from a version of Consul Enterprise 1.8 >= 1.8.13 or 1.9 >= 1.9.7. Other versions of Consul Enterprise are not forward compatible with v1.10 and will cause issues during the upgrade that could result in -agents failing to start due to [changes in the way we manage licenses](/docs/enterprise/license/faq). +agents failing to start due to [changes in the way we manage licenses](/consul/docs/enterprise/license/faq). ## Requirements - All Consul servers, clients, and snapshot agents should be on a version of Consul >= 1.8.0 and < 1.10.0. If - they are not at the minimum version or higher, follow the [normal upgrade procedures](/docs/upgrading) to upgrade them until the version requirement is met. + they are not at the minimum version or higher, follow the [normal upgrade procedures](/consul/docs/upgrading) to upgrade them until the version requirement is met. ## Assumptions This guides makes the following assumptions: -- You are familiar with the [General Upgrade Process](/docs/upgrading/instructions/general-process). +- You are familiar with the [General Upgrade Process](/consul/docs/upgrading/instructions/general-process). - You have the ability to run Consul CLI commands. - If ACLs are in use, then you possess a token with at least `operator:read` permissions. ## Considerations -The licensing changes outlined on the [Specific Version Details](/docs/upgrading/upgrade-specific#consul-1-10-0) +The licensing changes outlined on the [Specific Version Details](/consul/docs/upgrading/upgrade-specific#consul-1-10-0) page are the main breaking changes in Consul Enterprise 1.10 that require special handling during the upgrade process. The page also describes other changes that might cause issues during an upgrade. -You can also review the [licensing FAQ](/docs/enterprise/license/faq), which includes granular details, as well as the full +You can also review the [licensing FAQ](/consul/docs/enterprise/license/faq), which includes granular details, as well as the full [changelog](https://github.com/hashicorp/consul/blob/main/CHANGELOG.md#1100-june-22-2021). We strongly recommend reviewing the changes prior to upgrading. @@ -54,8 +54,8 @@ We strongly recommend reviewing the changes prior to upgrading. ~> Any steps in the following section that mention upgrading servers/clients assume that normal safe upgrade procedures are followed. Licensing-related configuration changes are required for upgrading to 1.10. Intermediate version upgrades are also required to ensure forward compatibility. -Refer to our documentation for the [basic server upgrade process](/docs/upgrading/instructions/general-process), -and for [autopilot assisted upgrades](https://learn.hashicorp.com/tutorials/consul/upgrade-automation) +Refer to our documentation for the [basic server upgrade process](/consul/docs/upgrading/instructions/general-process), +and for [autopilot assisted upgrades](/consul/tutorials/datacenter-operations/upgrade-automation) for more information. **1.** Retrieve the datacenter's current license by executing the following CLI command: @@ -113,7 +113,7 @@ are operating Consul within Kubernetes. **5.** Upgrade all client agents to the latest 1.8.x or 1.9.x release. -**6.** Upgrade all [snapshot agents](/commands/snapshot/agent) to the latest 1.8.x or 1.9.x release. +**6.** Upgrade all [snapshot agents](/consul/commands/snapshot/agent) to the latest 1.8.x or 1.9.x release. **7.** Take a snapshot of the upgraded cluster by running the following command: @@ -122,7 +122,7 @@ consul snapshot save intermediate.snap ``` Note that you can run the command from anywhere Consul is already running or from a location that has network access to the cluster. -If run elsewhere, [additional command line options](/commands/snapshot/save#api-options) may be needed to direct the request to the right Consul API. +If run elsewhere, [additional command line options](/consul/commands/snapshot/save#api-options) may be needed to direct the request to the right Consul API. Note that you will need to ensure there is enough disk space in the current directory to store the snapshot. In the worst case, the snapshot size could be close to the amount @@ -135,21 +135,21 @@ the snapshot would make it possible to restore the previous state. This can either be set with the `license_path` configuration item, the `CONSUL_LICENSE_PATH` environment variable, or the `CONSUL_LICENSE` -environment variable. See the [licensing documentation](/docs/enterprise/license/overview) +environment variable. See the [licensing documentation](/consul/docs/enterprise/license/overview) for more information about how to configure the license. -You can also refer to the [Apply Enterprise License](https://learn.hashicorp.com/tutorials/consul/deployment-guide#apply-enterprise-license) tutorial for additional information. +You can also refer to the [Apply Enterprise License](/consul/tutorials/production-deploy/deployment-guide#apply-enterprise-license) tutorial for additional information. **9.** Upgrade all server agents to latest v1.10.x. **10.** Upgrade all client agents to latest v1.10.x. -**11.** Upgrade all [snapshot agents](/commands/snapshot/agent) to latest v1.10.x. +**11.** Upgrade all [snapshot agents](/consul/commands/snapshot/agent) to latest v1.10.x.     ~> We do not recommend running in production with ACLs disabled. An alternative upgrade -path involves first enabling ACLs by following [this tutorial](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) +path involves first enabling ACLs by following [this tutorial](/consul/tutorials/security/access-control-setup-production) and then proceeding with the instructions within the "ACLs Enabled" tab. **4.** Upgrade all server agents to the latest 1.8.x or 1.9.x release. @@ -158,9 +158,9 @@ and then proceeding with the instructions within the "ACLs Enabled" tab. This can either be set with the `license_path` configuration item, the `CONSUL_LICENSE_PATH` environment variable, or the `CONSUL_LICENSE` -environment variable. See the [licensing documentation](/docs/enterprise/license/overview) +environment variable. See the [licensing documentation](/consul/docs/enterprise/license/overview) for more information about how to configure the license. -You can also refer to the [Apply Enterprise License](https://learn.hashicorp.com/tutorials/consul/deployment-guide#apply-enterprise-license) tutorial for additional information. +You can also refer to the [Apply Enterprise License](/consul/tutorials/production-deploy/deployment-guide#apply-enterprise-license) tutorial for additional information. Note that while Consul Enterprise 1.8.13 and 1.9.7 have the ability to load the license from these configurations, it is intended to only be used during upgrades. Licenses loaded this way are not online reloadable. It is therefore important @@ -171,7 +171,7 @@ to promptly proceed with the upgrade and not leave agents in the intermediate st **7.** Pre-configure the snapshot agents with a license. This is the same process that was executed for the servers in step 5. -**8.** Upgrade all [snapshot agents](/commands/snapshot/agent) to the latest 1.8.x or 1.9.x release. +**8.** Upgrade all [snapshot agents](/consul/commands/snapshot/agent) to the latest 1.8.x or 1.9.x release. **9.** Take a snapshot of the upgraded cluster by running the following command: @@ -196,7 +196,7 @@ was executed for the servers in step 5. **12.** Upgrade all client agents to latest v1.10.x. -**13.** Upgrade all [snapshot agents](/commands/snapshot/agent) to latest v1.10.x. +**13.** Upgrade all [snapshot agents](/consul/commands/snapshot/agent) to latest v1.10.x. @@ -213,9 +213,9 @@ values `server.enterpriseLicense.secretName` and `server.enterpriseLicense.secre **7.** Upgrade the cluster. -Follow the steps in the [Kubernetes Upgrade Guide](/docs/k8s/upgrade#upgrade-consul-on-kubernetes) -to upgrade the cluster. Ensure you check the steps to upgrade the [servers](/docs/k8s/upgrade#upgrading-consul-servers) -and the [clients](/docs/k8s/upgrade#upgrading-consul-clients). +Follow the steps in the [Kubernetes Upgrade Guide](/consul/docs/k8s/upgrade#upgrade-consul-on-kubernetes) +to upgrade the cluster. Ensure you check the steps to upgrade the [servers](/consul/docs/k8s/upgrade#upgrading-consul-servers) +and the [clients](/consul/docs/k8s/upgrade#upgrading-consul-clients). **8.** **If** the Consul servers are running outside the Kubernetes cluster, ensure they are upgraded to 1.10.0 before the next steps. Otherwise, this step can be skipped. @@ -223,9 +223,9 @@ to 1.10.0 before the next steps. Otherwise, this step can be skipped. This will require pre-configuring the servers with a license before running 1.10. This can either be set with the `license_path` configuration item, the `CONSUL_LICENSE_PATH` environment variable or the `CONSUL_LICENSE` -environment variable. See the [licensing documentation](/docs/enterprise/license/overview) +environment variable. See the [licensing documentation](/consul/docs/enterprise/license/overview) for more information about how to configure the license. -You can also refer to the [Apply Enterprise License](https://learn.hashicorp.com/tutorials/consul/deployment-guide#apply-enterprise-license) tutorial for additional information. +You can also refer to the [Apply Enterprise License](/consul/tutorials/production-deploy/deployment-guide#apply-enterprise-license) tutorial for additional information. Note that while Consul Enterprise 1.8.13 and 1.9.7 have the ability to load the license from these configurations, it is intended to only be used during upgrades. Licenses loaded this way are not online reloadable. It is therefore important @@ -235,9 +235,9 @@ to promptly proceed with the upgrade and not leave agents in the intermediate st **10.** Upgrade the cluster. -Follow the steps in the [Kubernetes Upgrade Guide](/docs/k8s/upgrade#upgrade-consul-on-kubernetes) -to then upgrade the cluster. Ensure you check the steps to upgrade the [servers](/docs/k8s/upgrade#upgrading-consul-servers) -and the [clients](/docs/k8s/upgrade#upgrading-consul-clients). +Follow the steps in the [Kubernetes Upgrade Guide](/consul/docs/k8s/upgrade#upgrade-consul-on-kubernetes) +to then upgrade the cluster. Ensure you check the steps to upgrade the [servers](/consul/docs/k8s/upgrade#upgrading-consul-servers) +and the [clients](/consul/docs/k8s/upgrade#upgrading-consul-clients). diff --git a/website/content/docs/upgrading/instructions/upgrade-to-1-2-x.mdx b/website/content/docs/upgrading/instructions/upgrade-to-1-2-x.mdx index 45ca864012..93f2451f8d 100644 --- a/website/content/docs/upgrading/instructions/upgrade-to-1-2-x.mdx +++ b/website/content/docs/upgrading/instructions/upgrade-to-1-2-x.mdx @@ -13,7 +13,7 @@ description: >- This guide explains how to best upgrade a multi-datacenter Consul deployment that is using a version of Consul >= 0.8.5 and < 1.2.4 while maintaining replication. If you are on a version older than 0.8.5, but are in the 0.8.x series, please upgrade to 0.8.5 by following our -[General Upgrade Process](/docs/upgrading/instructions/general-process). If you are on a version +[General Upgrade Process](/consul/docs/upgrading/instructions/general-process). If you are on a version older than 0.8.0, please [contact support](https://support.hashicorp.com). In this guide, we will be using an example with two datacenters (DCs) and will be @@ -25,7 +25,7 @@ referring to them as DC1 and DC2. DC1 will be the primary datacenter. - You need a Consul cluster with at least 3 nodes to perform this upgrade as documented. If you either have a single node cluster or several single node clusters joined via WAN, the servers will come up in a `No cluster leader` loop after upgrading. If that happens, you will - need to recover the cluster using the method described [here](https://learn.hashicorp.com/tutorials/consul/recovery-outage#manual-recovery-using-peers-json). + need to recover the cluster using the method described [here](/consul/tutorials/datacenter-operations/recovery-outage#manual-recovery-using-peers-json). You can avoid this issue entirely by growing your cluster to 3 nodes prior to upgrading. ## Assumptions @@ -39,7 +39,7 @@ This guide makes the following assumptions: ## Considerations There are not too many major changes that might cause issues upgrading from 1.0.8, but notable changes -are called out in our [Specific Version Details](/docs/upgrading/upgrade-specific#consul-1-1-0) +are called out in our [Specific Version Details](/consul/docs/upgrading/upgrade-specific#consul-1-1-0) page. You can find more granular details in the full [changelog](https://github.com/hashicorp/consul/blob/main/CHANGELOG.md#124-november-27-2018). Looking through these changes prior to upgrading is highly recommended. @@ -88,7 +88,7 @@ You should receive output similar to this: } ``` -**3.** Upgrade the Consul agents in all DCs to version 1.2.4 by following our [General Upgrade Process](/docs/upgrading/instructions/general-process). +**3.** Upgrade the Consul agents in all DCs to version 1.2.4 by following our [General Upgrade Process](/consul/docs/upgrading/instructions/general-process). This should be done one DC at a time, leaving the primary DC for last. **4.** Confirm that replication is still working in DC2 by issuing the following curl command from a @@ -120,7 +120,7 @@ moving to newer versions. The full list of changes is available here: -- [Upgrade Specific Versions: Consul 1.0 - Deprecated Options](/docs/upgrading/upgrade-specific#deprecated-options-have-been-removed) +- [Upgrade Specific Versions: Consul 1.0 - Deprecated Options](/consul/docs/upgrading/upgrade-specific#deprecated-options-have-been-removed) You can make sure your config changes are valid by copying your existing configuration files, making the changes, and then verifying them by using `consul validate $CONFIG_FILE1_PATH $CONFIG_FILE2_PATH ...`. diff --git a/website/content/docs/upgrading/instructions/upgrade-to-1-6-x.mdx b/website/content/docs/upgrading/instructions/upgrade-to-1-6-x.mdx index a86c1df5e9..8a12ca8113 100644 --- a/website/content/docs/upgrading/instructions/upgrade-to-1-6-x.mdx +++ b/website/content/docs/upgrading/instructions/upgrade-to-1-6-x.mdx @@ -12,15 +12,15 @@ description: >- This guide explains how to best upgrade a multi-datacenter Consul deployment that is using a version of Consul >= 1.2.4 and < 1.6.10 while maintaining replication. If you are on a version -older than 1.2.4, please review our [Upgrading to 1.2.4](/docs/upgrading/instructions/upgrade-to-1-2-x) +older than 1.2.4, please review our [Upgrading to 1.2.4](/consul/docs/upgrading/instructions/upgrade-to-1-2-x) guide. Due to changes to the ACL system, an ACL token migration will need to be performed as part of this upgrade. The 1.6.x series is the last series that had support for legacy ACL tokens, so this migration _must_ happen before upgrading past the 1.6.x release series. Here is some documentation that may prove useful for reference during this upgrade process: -- [ACL System in Legacy Mode](/docs/security/acl/acl-legacy) - You can find +- [ACL System in Legacy Mode](/consul/docs/security/acl/acl-legacy) - You can find information about legacy configuration options and differences between modes here. -- [Configuration](/docs/agent/config) - You can find more details +- [Configuration](/consul/docs/agent/config) - You can find more details around legacy ACL and new ACL configuration options here. Legacy ACL config options will be listed as deprecates as of 1.4.0. @@ -44,14 +44,14 @@ This guide makes the following assumptions: ## Considerations There are quite a number of changes between releases. Notable changes -are called out in our [Specific Version Details](/docs/upgrading/upgrade-specific#consul-1-6-3) +are called out in our [Specific Version Details](/consul/docs/upgrading/upgrade-specific#consul-1-6-3) page. You can find more granular details in the full [changelog](https://github.com/hashicorp/consul/blob/main/CHANGELOG.md#124-november-27-2018). Looking through these changes prior to upgrading is highly recommended. Two very notable items are: - 1.6.2 introduced more strict JSON decoding. Invalid JSON that was previously ignored might result in errors now (e.g., `Connect: null` in service definitions). See [[GH#6680](https://github.com/hashicorp/consul/pull/6680)]. -- 1.6.3 introduced the [http_max_conns_per_client](/docs/agent/config/config-files#http_max_conns_per_client) limit. This defaults to 200. Prior to this, connections per client were unbounded. [[GH#7159](https://github.com/hashicorp/consul/issues/7159)] +- 1.6.3 introduced the [http_max_conns_per_client](/consul/docs/agent/config/config-files#http_max_conns_per_client) limit. This defaults to 200. Prior to this, connections per client were unbounded. [[GH#7159](https://github.com/hashicorp/consul/issues/7159)] ## Procedure @@ -98,7 +98,7 @@ You should receive output similar to this: } ``` -**3.** Upgrade DC2 agents to version 1.6.10 by following our [General Upgrade Process](/docs/upgrading/instructions/general-process). _**Leave all DC1 agents at 1.2.4.**_ You should start observing log messages like this after that: +**3.** Upgrade DC2 agents to version 1.6.10 by following our [General Upgrade Process](/consul/docs/upgrading/instructions/general-process). _**Leave all DC1 agents at 1.2.4.**_ You should start observing log messages like this after that: ```log 2020/09/08 15:51:29 [DEBUG] acl: Cannot upgrade to new ACLs, servers in acl datacenter have not upgraded - found servers: true, mode: 3 @@ -158,7 +158,7 @@ Failed to retrieve the token list: Unexpected response code: 500 (The ACL system This is because Consul in legacy mode. ACL CLI commands will not work and you have to hit the old ACL HTTP endpoints (which is why `curl` is being used above rather than the `consul` CLI client). -**5.** Upgrade DC1 agents to version 1.6.10 by following our [General Upgrade Process](/docs/upgrading/instructions/general-process). +**5.** Upgrade DC1 agents to version 1.6.10 by following our [General Upgrade Process](/consul/docs/upgrading/instructions/general-process). Once this is complete, you should observe a log entry like this from your server agents: @@ -189,7 +189,7 @@ You should receive output similar to this: } ``` -**6.** Migrate your legacy ACL tokens to the new ACL system by following the instructions in our [ACL Token Migration guide](/docs/security/acl/acl-migrate-tokens). +**6.** Migrate your legacy ACL tokens to the new ACL system by following the instructions in our [ACL Token Migration guide](/consul/docs/security/acl/acl-migrate-tokens). ~> This step _must_ be completed before upgrading to a version higher than 1.6.x. @@ -202,8 +202,8 @@ update those now to avoid issues when moving to newer versions. These are the changes you will need to make: -- `acl_datacenter` is now named `primary_datacenter` (review our [docs](/docs/agent/config/config-files#primary_datacenter) for more info) -- `acl_default_policy`, `acl_down_policy`, `acl_ttl`, `acl_*_token` and `enable_acl_replication` options are now specified like this (review our [docs](/docs/agent/config/config-files#acl) for more info): +- `acl_datacenter` is now named `primary_datacenter` (review our [docs](/consul/docs/agent/config/config-files#primary_datacenter) for more info) +- `acl_default_policy`, `acl_down_policy`, `acl_ttl`, `acl_*_token` and `enable_acl_replication` options are now specified like this (review our [docs](/consul/docs/agent/config/config-files#acl) for more info): ```hcl acl { enabled = true/false diff --git a/website/content/docs/upgrading/instructions/upgrade-to-1-8-x.mdx b/website/content/docs/upgrading/instructions/upgrade-to-1-8-x.mdx index 1ba264546e..7df5626c42 100644 --- a/website/content/docs/upgrading/instructions/upgrade-to-1-8-x.mdx +++ b/website/content/docs/upgrading/instructions/upgrade-to-1-8-x.mdx @@ -12,7 +12,7 @@ description: >- This guide explains how to best upgrade a multi-datacenter Consul deployment that is using a version of Consul >= 1.6.9 and < 1.8.19 while maintaining replication. If you are on a version -older than 1.6.9, please follow the link for the version you are on from [here](/docs/upgrading/instructions). +older than 1.6.9, please follow the link for the version you are on from [here](/consul/docs/upgrading/instructions). In this guide, we will be using an example with two datacenters (DCs) and will be referring to them as DC1 and DC2. DC1 will be the primary datacenter. @@ -32,7 +32,7 @@ This guides makes the following assumptions: ## Considerations There are not too many major changes that might cause issues upgrading from 1.6.9, but notable changes -are called out in our [Specific Version Details](/docs/upgrading/upgrade-specific#consul-1-8-0) +are called out in our [Specific Version Details](/consul/docs/upgrading/upgrade-specific#consul-1-8-0) page. You can find more granular details in the full [changelog](https://github.com/hashicorp/consul/blob/main/CHANGELOG.md#183-august-12-2020). Looking through these changes prior to upgrading is highly recommended. @@ -87,7 +87,7 @@ You should receive output similar to this: } ``` -**3.** Upgrade the Consul agents in all DCs to version 1.8.19 by following our [General Upgrade Process](/docs/upgrading/instructions/general-process). +**3.** Upgrade the Consul agents in all DCs to version 1.8.19 by following our [General Upgrade Process](/consul/docs/upgrading/instructions/general-process). **4.** Confirm that replication is still working in DC2 by issuing the following curl command from a consul server in that DC: diff --git a/website/content/docs/upgrading/upgrade-specific.mdx b/website/content/docs/upgrading/upgrade-specific.mdx index 12d9b98a79..70502bfda5 100644 --- a/website/content/docs/upgrading/upgrade-specific.mdx +++ b/website/content/docs/upgrading/upgrade-specific.mdx @@ -8,7 +8,7 @@ description: >- # Upgrading Specific Versions -The [upgrading page](/docs/upgrading) covers the details of doing a +The [upgrading page](/consul/docs/upgrading) covers the details of doing a standard upgrade. However, specific versions of Consul may have more details provided for their upgrades as a result of new features or changed behavior. This page is used to document those details separately from the standard @@ -92,12 +92,12 @@ In Consul v1.15 and higher: ### Service Mesh Compatibility Prior to Consul 1.14, cluster peering or Consul connect were disabled by default. A breaking change was made in Consul 1.14 that: -- [Cluster Peering is enabled by default.](/docs/connect/cluster-peering) +- [Cluster Peering is enabled by default.](/consul/docs/connect/cluster-peering) Cluster peering and WAN federation can coexist, so there is no need to disable cluster peering to upgrade existing WAN federated datacenters. - To disable cluster peering nonetheless, set [`peering.enabled`](/docs/agent/config/config-files#peering_enabled) to `false`. -- [Consul Connect is enabled by default.](/docs/connect) - To disable, set [`connect.enabled`](/docs/agent/config/config-files#connect_enabled) to `false`. + To disable cluster peering nonetheless, set [`peering.enabled`](/consul/docs/agent/config/config-files#peering_enabled) to `false`. +- [Consul Connect is enabled by default.](/consul/docs/connect) + To disable, set [`connect.enabled`](/consul/docs/agent/config/config-files#connect_enabled) to `false`. The changes to Consul service mesh in version 1.14 are incompatible with Nomad 1.4.2 and earlier. If you operate Consul service mesh using Nomad 1.4.2 or earlier, do not upgrade to Consul 1.14 until @@ -112,34 +112,34 @@ conjunction with TLS-encrypted HTTP APIs. #### Changes to gRPC TLS configuration -**Make configuration changes** if using [`ports.grpc`](/docs/agent/config/config-files#grpc_port) in conjunction with any of the following settings that enables encryption: -1. [`tls.grpc`](/docs/agent/config/config-files#tls_grpc) -1. [`tls.defaults`](/docs/agent/config/config-files#tls_defaults) -1. [`auto_encrypt`](/docs/agent/config/config-files#auto_encrypt) -1. [`auto_config`](/docs/agent/config/config-files#auto_config) +**Make configuration changes** if using [`ports.grpc`](/consul/docs/agent/config/config-files#grpc_port) in conjunction with any of the following settings that enables encryption: +1. [`tls.grpc`](/consul/docs/agent/config/config-files#tls_grpc) +1. [`tls.defaults`](/consul/docs/agent/config/config-files#tls_defaults) +1. [`auto_encrypt`](/consul/docs/agent/config/config-files#auto_encrypt) +1. [`auto_config`](/consul/docs/agent/config/config-files#auto_config) Prior to Consul 1.14, it was possible to encrypt communication between Consul and Envoy over `ports.grpc` using these settings. -Consul 1.14 introduces [`ports.grpc_tls`](/docs/agent/config/config-files#grpc_tls_port), a new configuration -for encrypting communication over gRPC. The existing [`ports.grpc`](/docs/agent/config/config-files#grpc_port) configuration **no longer supports encryption**. As of version 1.14, -[`ports.grpc_tls`](/docs/agent/config/config-files#grpc_tls_port) is the only port that serves encrypted gRPC traffic. +Consul 1.14 introduces [`ports.grpc_tls`](/consul/docs/agent/config/config-files#grpc_tls_port), a new configuration +for encrypting communication over gRPC. The existing [`ports.grpc`](/consul/docs/agent/config/config-files#grpc_port) configuration **no longer supports encryption**. As of version 1.14, +[`ports.grpc_tls`](/consul/docs/agent/config/config-files#grpc_tls_port) is the only port that serves encrypted gRPC traffic. The default value for the gRPC TLS port is 8503 for Consul servers. To disable the gRPC TLS port, use value -1. If you already use gRPC encryption, change the following fields to ensure compatibility: -+ Change `ports.grpc` to `ports.grpc_tls`. Refer to the [`grpc_tls_port` documentation](/docs/agent/config/config-files#grpc_tls_port) for details. -+ Change `addresses.grpc` to `addresses.grpc_tls`. Refer to the [`grpc_tls` documentation](/docs/agent/config/config-files#grpc_tls) for details. ++ Change `ports.grpc` to `ports.grpc_tls`. Refer to the [`grpc_tls_port` documentation](/consul/docs/agent/config/config-files#grpc_tls_port) for details. ++ Change `addresses.grpc` to `addresses.grpc_tls`. Refer to the [`grpc_tls` documentation](/consul/docs/agent/config/config-files#grpc_tls) for details. + Update `consul connect envoy` command invocations to specify gRPC CA certificates with one of the new configuration options: -[`-grpc-ca-file`](/commands/connect/envoy#grpc-ca-file) or -[`-grpc-ca-path`](/commands/connect/envoy#grpc-ca-path) +[`-grpc-ca-file`](/consul/commands/connect/envoy#grpc-ca-file) or +[`-grpc-ca-path`](/consul/commands/connect/envoy#grpc-ca-path) (or their corresponding environment variables). #### Changes to peering -[Cluster peering](/docs/connect/cluster-peering) was released in Consul 1.13 as an experimental feature. +[Cluster peering](/consul/docs/connect/cluster-peering) was released in Consul 1.13 as an experimental feature. In Consul 1.14, cluster peering has been improved and is now considered stable. All experimental peering connections created by 1.13 should be -[deleted](/docs/connect/cluster-peering/create-manage-peering#delete-peering-connections) +[deleted](/consul/docs/connect/cluster-peering/create-manage-peering#delete-peering-connections) prior to upgrading, as they will no longer be compatible with 1.14. ## Consul 1.13.x @@ -168,8 +168,8 @@ This bug is fixed in Consul versions 1.13.1 and newer. #### Service mesh deployments using auto-encrypt or auto-config Upgrade to **Consul version 1.13.2 or later** if using -[auto-encrypt](/docs/agent/config/config-files#auto_encrypt) or -[auto-config](/docs/agent/config/config-files#auto_config). +[auto-encrypt](/consul/docs/agent/config/config-files#auto_encrypt) or +[auto-config](/consul/docs/agent/config/config-files#auto_config). In Consul 1.13.0 - 1.13.1, auto-encrypt and auto-config both cause Consul to require TLS for gRPC communication with Envoy proxies. @@ -178,7 +178,7 @@ to use TLS for gRPC, upgrading to Consul 1.13.0 - 1.13.1 will cause Envoy proxies to disconnect from the control plane (Consul agents). If upgrading to version 1.13.2 or later, you must enable -[tls.grpc.use_auto_cert](/docs/agent/config/config-files#use_auto_cert) +[tls.grpc.use_auto_cert](/consul/docs/agent/config/config-files#use_auto_cert) if you currently rely on Consul agents presenting the auto-encrypt or auto-config certs as the TLS server certs on the gRPC port. The new `use_auto_cert` flag enables TLS for gRPC based on the presence @@ -187,7 +187,7 @@ of auto-encrypt certs. #### Service mesh deployments without the HTTPS port enabled on Consul agents ((#grpc-tls)) If the HTTPS port is not enabled -([`ports { https = POSITIVE_INTEGER }`](/docs/agent/config/config-files#https_port)) +([`ports { https = POSITIVE_INTEGER }`](/consul/docs/agent/config/config-files#https_port)) on a pre-1.13 Consul agent, **[modify the agent's TLS configuration before upgrading](#modify-the-consul-agent-s-tls-configuration)** to avoid Envoy proxies disconnecting from the control plane (Consul agents). @@ -203,7 +203,7 @@ Envoy proxies when using Consul service mesh. A Consul agent's gRPC traffic is often loopback-only, which TLS encryption is not important for. -Prior to Consul 1.13, if [`ports { https = POSITIVE_INTEGER }`](/docs/agent/config/config-files#https_port) +Prior to Consul 1.13, if [`ports { https = POSITIVE_INTEGER }`](/consul/docs/agent/config/config-files#https_port) was configured, TLS was enabled for both HTTP *and* gRPC. This was inconvenient for deployments that needed TLS for HTTP, but not for gRPC. @@ -213,15 +213,15 @@ with its Consul agent via TLS over gRPC. Consul 1.13 addresses this inconvenience by fully decoupling the TLS configuration for HTTP and gRPC interfaces. TLS for gRPC is no longer enabled by setting -[`ports { https = POSITIVE_INTEGER }`](/docs/agent/config/config-files#https_port). +[`ports { https = POSITIVE_INTEGER }`](/consul/docs/agent/config/config-files#https_port). TLS configuration for gRPC is now determined exclusively by: -1. [`tls.grpc`](/docs/agent/config/config-files#tls_grpc), which overrides -1. [`tls.defaults`](/docs/agent/config/config-files#tls_defaults), which overrides -1. [Deprecated TLS options](/docs/agent/config/config-files#tls_deprecated_options) such as - [`ca_file`](/docs/agent/config/config-files#ca_file-4), - [`cert_file`](/docs/agent/config/config-files#cert_file-4), and - [`key_file`](/docs/agent/config/config-files#key_file-4). +1. [`tls.grpc`](/consul/docs/agent/config/config-files#tls_grpc), which overrides +1. [`tls.defaults`](/consul/docs/agent/config/config-files#tls_defaults), which overrides +1. [Deprecated TLS options](/consul/docs/agent/config/config-files#tls_deprecated_options) such as + [`ca_file`](/consul/docs/agent/config/config-files#ca_file-4), + [`cert_file`](/consul/docs/agent/config/config-files#cert_file-4), and + [`key_file`](/consul/docs/agent/config/config-files#key_file-4). This decoupling has a side effect that requires a [TLS configuration change](#modify-the-consul-agent-s-tls-configuration) @@ -233,46 +233,46 @@ that continue to use gRPC *without* TLS. ##### Modify the Consul agent's TLS configuration -If [`tls.grpc`](/docs/agent/config/config-files#tls_grpc), -[`tls.defaults`](/docs/agent/config/config-files#tls_defaults), -or the [deprecated TLS options](/docs/agent/config/config-files#tls_deprecated_options) +If [`tls.grpc`](/consul/docs/agent/config/config-files#tls_grpc), +[`tls.defaults`](/consul/docs/agent/config/config-files#tls_defaults), +or the [deprecated TLS options](/consul/docs/agent/config/config-files#tls_deprecated_options) define TLS material in their `ca_file`, `ca_path`, `cert_file`, or `key_file` fields, TLS for gRPC will be enabled in Consul 1.13, even if -[`ports { https = POSITIVE_INTEGER }`](/docs/agent/config/config-files#https_port) +[`ports { https = POSITIVE_INTEGER }`](/consul/docs/agent/config/config-files#https_port) is not set. This will cause Envoy proxies to disconnect from the control plane after upgrading to Consul 1.13 if associated pre-1.13 Consul agents have **not** set -[`ports { https = POSITIVE_INTEGER }`](/docs/agent/config/config-files#https_port). +[`ports { https = POSITIVE_INTEGER }`](/consul/docs/agent/config/config-files#https_port). To avoid this problem, make the following agent configuration changes: 1. Remove TLS material from the Consul agents' interface-generic TLS configuration options: - [`tls.defaults`](/docs/agent/config/config-files#tls_grpc) and - [deprecated TLS options](/docs/agent/config/config-files#tls_deprecated_options) + [`tls.defaults`](/consul/docs/agent/config/config-files#tls_grpc) and + [deprecated TLS options](/consul/docs/agent/config/config-files#tls_deprecated_options) 1. Reapply TLS material to the non-gRPC interfaces that need it with the interface-specific TLS configuration stanzas - [introduced in Consul 1.12](/docs/upgrading/upgrade-specific#tls-configuration): - [`tls.https`](/docs/agent/config/config-files#tls_https) and - [`tls.internal_rpc`](/docs/agent/config/config-files#tls_internal_rpc). + [introduced in Consul 1.12](/consul/docs/upgrading/upgrade-specific#tls-configuration): + [`tls.https`](/consul/docs/agent/config/config-files#tls_https) and + [`tls.internal_rpc`](/consul/docs/agent/config/config-files#tls_internal_rpc). If upgrading directly from pre-1.12 Consul, the above configuration change cannot be made before upgrading. Therefore, consider upgrading agents to Consul 1.12 before upgrading to 1.13. If pre-1.13 Consul agents have set -[`ports { https = POSITIVE_INTEGER }`](/docs/agent/config/config-files#https_port), +[`ports { https = POSITIVE_INTEGER }`](/consul/docs/agent/config/config-files#https_port), this configuration change is not required to upgrade. That setting means the pre-1.13 Consul agent requires TLS for gRPC *already*, and will continue to do so after upgrading to 1.13. If your pre-1.13 service mesh is working, you have already configured your Envoy proxies to use TLS for gRPC when bootstrapping Envoy -via [`consul connect envoy`](/commands/connect/envoy), +via [`consul connect envoy`](/consul/commands/connect/envoy), such as with flags or environment variables like -[`-ca-file`](/commands/connect/envoy#ca-file) and -[`CONSUL_CACERT`](/commands#consul_cacert). +[`-ca-file`](/consul/commands/connect/envoy#ca-file) and +[`CONSUL_CACERT`](/consul/commands#consul_cacert). #### Modify Vault policy for Vault CA provider @@ -281,12 +281,12 @@ modify the Vault policy used by Consul to interact with Vault to ensure that certificates required for service mesh operation can still be generated. The policy must include the `update` capability on the intermediate PKI's tune mount configuration endpoint at path `/sys/mounts//tune`. -Refer to the [Vault CA provider documentation](/docs/connect/ca/vault#vault-acl-policies) +Refer to the [Vault CA provider documentation](/consul/docs/connect/ca/vault#vault-acl-policies) for updated example Vault policies for use with Vault-managed or Consul-managed PKI paths. You are using the Vault CA provider if either of the following configurations exists: -- The Consul server agent configuration option [`connect.ca_provider`](/docs/agent/config/config-files#connect_ca_provider) is set to `vault`, or -- The Consul on Kubernetes Helm Chart [`global.secretsBackend.vault.connectCA`](/docs/k8s/helm#v-global-secretsbackend-vault-connectca) value is configured. +- The Consul server agent configuration option [`connect.ca_provider`](/consul/docs/agent/config/config-files#connect_ca_provider) is set to `vault`, or +- The Consul on Kubernetes Helm Chart [`global.secretsBackend.vault.connectCA`](/consul/docs/k8s/helm#v-global-secretsbackend-vault-connectca) value is configured. Though this guidance is listed in the 1.13.x section, it applies to several release series. Affected Consul versions contain a @@ -312,7 +312,7 @@ to ensure the operation of your service mesh and to enable CA TTL modification. #### Removing configuration options -The [`disable_compat_19`](/docs/agent/config/config-files#telemetry-disable_compat_1.9) telemetry configuration option is now removed. +The [`disable_compat_19`](/consul/docs/agent/config/config-files#telemetry-disable_compat_1.9) telemetry configuration option is now removed. In prior Consul versions (1.10.x through 1.11.x), the config defaulted to `false`. In 1.12.x it defaulted to `true`. If you were using this flag, you must remove it before upgrading. @@ -340,7 +340,7 @@ to Consul 1.12.6 or later to avoid the breaking nature of that change. #### Changing the default behavior for option -The [`disable_compat_19`](/docs/agent/config/config-files#telemetry-disable_compat_1.9) telemetry configuration option now defaults +The [`disable_compat_19`](/consul/docs/agent/config/config-files#telemetry-disable_compat_1.9) telemetry configuration option now defaults to `true`. In prior Consul versions (1.10.x through 1.11.x), the config defaulted to `false`. If you require 1.9 style `consul.http...` metrics, you may enable them by setting the flag to `false`. However, be advised that these metrics, as well as the flag will be removed in upcoming Consul 1.13. We recommend changing your instrumentation to use 1.10 and later @@ -358,7 +358,7 @@ The Consul Enterprise codebase was updated with a fix for this issue in version You can now configure TLS differently for each of Consul's exposed ports. As a result, the following top-level configuration fields are deprecated and should -be replaced with the new [`tls` stanza](/docs/agent/config/config-files#tls-configuration-reference): +be replaced with the new [`tls` stanza](/consul/docs/agent/config/config-files#tls-configuration-reference): - `cert_file` - `key_file` @@ -394,14 +394,14 @@ The old names have been deprecated and will be removed at a future date. Due to this rename the following endpoint is also deprecated: -- [`PUT /v1/agent/token/agent_master`](/api-docs/agent#update-acl-tokens) +- [`PUT /v1/agent/token/agent_master`](/consul/api-docs/agent#update-acl-tokens) ### Deprecated Agent Config Options These config keys are now deprecated: - `audit.sink[].name` - - [`dns_config.dns_prefer_namespace`](/docs/agent/config/config-files#dns_prefer_namespace) + - [`dns_config.dns_prefer_namespace`](/consul/docs/agent/config/config-files#dns_prefer_namespace) ### Deprecated CLI Subcommands @@ -416,13 +416,13 @@ system. Complete the [Migrate Legacy ACL Tokens](https://learn.hashicorp.com/con Due to this removal the following endpoints no longer function: - - [`PUT /v1/acl/create`](/api-docs/acl/legacy#create-acl-token) - - [`PUT /v1/acl/update`](/api-docs/acl/legacy#update-acl-token) - - [`PUT /v1/acl/destroy/`](/api-docs/acl/legacy#delete-acl-token) - - [`GET /v1/acl/info/`](/api-docs/acl/legacy#read-acl-token) - - [`PUT /v1/acl/clone/`](/api-docs/acl/legacy#clone-acl-token) - - [`GET /v1/acl/list`](/api-docs/acl/legacy#list-acls) - - [`GET,POST /v1/acl/rules/translate`](/api-docs/acl#translate-rules) + - [`PUT /v1/acl/create`](/consul/api-docs/acl/legacy#create-acl-token) + - [`PUT /v1/acl/update`](/consul/api-docs/acl/legacy#update-acl-token) + - [`PUT /v1/acl/destroy/`](/consul/api-docs/acl/legacy#delete-acl-token) + - [`GET /v1/acl/info/`](/consul/api-docs/acl/legacy#read-acl-token) + - [`PUT /v1/acl/clone/`](/consul/api-docs/acl/legacy#clone-acl-token) + - [`GET /v1/acl/list`](/consul/api-docs/acl/legacy#list-acls) + - [`GET,POST /v1/acl/rules/translate`](/consul/api-docs/acl#translate-rules) ### Raft Storage Changes @@ -464,7 +464,7 @@ to Consul 1.11.11 or later to avoid the breaking nature of that change. Consul Enterprise 1.10 has removed temporary licensing capabilities from the binaries found on https://releases.hashicorp.com. Servers will no longer load a license previously set through the CLI or API. Instead the license must be present in the server's configuration -or environment prior to starting. See the [licensing documentation](/docs/enterprise/license/overview) +or environment prior to starting. See the [licensing documentation](/consul/docs/enterprise/license/overview) for more information about how to configure the license. Client agents previously retrieved their license from the servers in the cluster within 30 minutes of starting and the snapshot agent would similarly retrieve its license from the server or client agent it was configured to use. As @@ -473,13 +473,13 @@ have a license loaded from a configuration file or from their environment the sa agents must have the license specified. Both agents can still perform automatic retrieval of their license but with a few extra stipulations. First, license auto-retrieval now requires that ACLs are on and that the client or snapshot agent is configured with a valid ACL token. Secondly, client -agents require that either the [`start_join`](/docs/agent/config/config-files#start_join) or -[`retry_join`](/docs/agent/config/config-files#retry_join) configurations are set and that they resolve to server +agents require that either the [`start_join`](/consul/docs/agent/config/config-files#start_join) or +[`retry_join`](/consul/docs/agent/config/config-files#retry_join) configurations are set and that they resolve to server agents. If those stipulations are not met, attempting to start the client or snapshot agent will result in it immediately shutting down. -For the step by step upgrade procedures see the [Upgrading to 1.10.0](/docs/upgrading/instructions/upgrade-to-1-10-x) documentation. -For answers to common licensing questions please refer to the [FAQ](/docs/enterprise/license/faq) +For the step by step upgrade procedures see the [Upgrading to 1.10.0](/consul/docs/upgrading/instructions/upgrade-to-1-10-x) documentation. +For answers to common licensing questions please refer to the [FAQ](/consul/docs/enterprise/license/faq) ### Envoy xDS Protocol Upgrades @@ -503,7 +503,7 @@ In [Consul 1.11](#consul-1-11-0) the v2 State of the World protocol support will #### Escape Hatches -Any [escape hatches](/docs/connect/proxies/envoy#advanced-configuration) that +Any [escape hatches](/consul/docs/connect/proxies/envoy#advanced-configuration) that are defined will likely need to be switched from using xDS v2 to xDS v3 structures. Mostly this involves migrating off of deprecated (and now removed) fields and switching untyped config to [typed config](https://www.envoyproxy.io/docs/envoy/v1.17.2/configuration/overview/extension) @@ -521,10 +521,10 @@ and [after](https://github.com/hashicorp/consul/blob/71d45a34601423abdfc0a64d44c #### Stairstep Upgrade Path 1. Upgrade Envoy sidecars to the latest version of Envoy that is - [supported](/docs/connect/proxies/envoy#supported-versions) by the currently + [supported](/consul/docs/connect/proxies/envoy#supported-versions) by the currently running version of Consul as well as Consul 1.10.0. -1. Determine if you are using the [escape hatch](/docs/connect/proxies/envoy#advanced-configuration) +1. Determine if you are using the [escape hatch](/consul/docs/connect/proxies/envoy#advanced-configuration) feature. If so, rewrite the escape hatch to use the xDS v3 syntax and update the service registration to reflect the updated escape hatch configuration by re-registering. This should purge v2 elements from any configs. @@ -534,7 +534,7 @@ and [after](https://github.com/hashicorp/consul/blob/71d45a34601423abdfc0a64d44c of the World protocol to the new Consul instances without issue. 1. Once a Consul client is upgraded, use an updated CLI binary to re-bootstrap - and restart Envoy using [`consul connect envoy`](/commands/connect/envoy). + and restart Envoy using [`consul connect envoy`](/consul/commands/connect/envoy). This will ensure it switches over to the v3 Incremental xDS protocol. Depending upon how you have chosen to run Envoy this is either one step @@ -568,7 +568,7 @@ to Consul 1.9.0. ### Changes to Configuration Defaults -The [`enable_central_service_config`](/docs/agent/config/config-files#enable_central_service_config) +The [`enable_central_service_config`](/consul/docs/agent/config/config-files#enable_central_service_config) configuration now defaults to `true`. ### Changes to Intentions @@ -576,7 +576,7 @@ configuration now defaults to `true`. #### Namespaced Intentions The API endpoint to [list -intentions](/api-docs/connect/intentions#list-intentions) now accepts the same +intentions](/consul/api-docs/connect/intentions#list-intentions) now accepts the same `ns` query parameter (or `X-Consul-Namespace` header) used on other API endpoints. By default this will now only list the intentions in a specific namespace, rather than listing all intentions across all namespaces. To achieve @@ -586,14 +586,14 @@ namespace with a query parameter of `?ns=*`. #### Migration Upgrading to Consul 1.9.0 will trigger a one-time background migration of -[intentions](/docs/connect/intentions) into an equivalent set of -[`service-intentions`](/docs/connect/config-entries/service-intentions) config +[intentions](/consul/docs/connect/intentions) into an equivalent set of +[`service-intentions`](/consul/docs/connect/config-entries/service-intentions) config entries. This process will wait until all of the Consul servers in the primary datacenter are running Consul 1.9.0+. All write requests via either the [Intentions -API](/api-docs/connect/intentions) endpoints or [Config Entry -API](/api-docs/config) endpoints for a `service-intentions` kind will be +API](/consul/api-docs/connect/intentions) endpoints or [Config Entry +API](/consul/api-docs/config) endpoints for a `service-intentions` kind will be blocked until the migration process is complete after the upgrade. Reads will function normally throughout the migration, so authorization enforcement will be unaffected. @@ -605,7 +605,7 @@ upgrade the datacenters in any order. #### Deprecated Fields -All old ID-based [Intentions API](/api-docs/connect/intentions) CRUD endpoints +All old ID-based [Intentions API](/consul/api-docs/connect/intentions) CRUD endpoints will retain all of their prior fields _as long as those endpoints are exclusively used to edit intentions_. Once the underlying config entry representation is edited it will transition the intention into the newer format @@ -615,29 +615,29 @@ re-created via the old endpoints. Fields that are being removed or changing behavior: - `Intention.ID` after migration is stored in the - [`LegacyID`](/docs/connect/config-entries/service-intentions#legacyid) field. + [`LegacyID`](/consul/docs/connect/config-entries/service-intentions#legacyid) field. After transitioning this field is cleared. - `Intention.CreatedAt` after migration is stored in the - [`LegacyCreateTime`](/docs/connect/config-entries/service-intentions#legacycreatetime) + [`LegacyCreateTime`](/consul/docs/connect/config-entries/service-intentions#legacycreatetime) field. After transitioning this field is cleared. - `Intention.UpdatedAt` after migration is stored in the - [`LegacyUpdateTime`](/docs/connect/config-entries/service-intentions#legacyupdatetime) + [`LegacyUpdateTime`](/consul/docs/connect/config-entries/service-intentions#legacyupdatetime) field. After transitioning this field is cleared. - `Intention.Meta` after migration is stored in the - [`LegacyMeta`](/docs/connect/config-entries/service-intentions#legacymeta) + [`LegacyMeta`](/consul/docs/connect/config-entries/service-intentions#legacymeta) field. To complete the transition, this field **must be cleared manually** and the metadata moved up to the enclosing config entry's - [`Meta`](/docs/connect/config-entries/service-intentions#meta) field. This is + [`Meta`](/consul/docs/connect/config-entries/service-intentions#meta) field. This is not done automatically since it is potentially a lossy operation. ## Consul 1.8.0 #### Removal of Deprecated Features -The [`acl_enforce_version_8`](/docs/agent/config/config-files#acl_enforce_version_8) +The [`acl_enforce_version_8`](/consul/docs/agent/config/config-files#acl_enforce_version_8) configuration has been removed (with version 8 ACL support by being on by default). @@ -673,14 +673,14 @@ in OSS or `web.service.ns1.dc1.consul` for Enterprise. ### Telemetry: semantics of `consul.rpc.query` changed, see `consul.rpc.queries_blocking` -Consul has changed the semantics of query counts in its [telemetry](/docs/agent/telemetry#metrics-reference). +Consul has changed the semantics of query counts in its [telemetry](/consul/docs/agent/telemetry#metrics-reference). `consul.rpc.query` now only increments on the _start_ of a query (blocking or non-blocking), whereas before it would measure when blocking queries polled for more data. The `consul.rpc.queries_blocking` gauge has been added to more precisely capture the view of _active_ blocking queries. ### Vault: default `http_max_conns_per_client` too low to run Vault properly -Consul 1.7.0 introduced [limiting of connections per client](/docs/agent/config/config-files#http_max_conns_per_client). The default value +Consul 1.7.0 introduced [limiting of connections per client](/consul/docs/agent/config/config-files#http_max_conns_per_client). The default value was 100, but Vault could use up to 128, which caused problems. If you want to use Vault with Consul 1.7.0, you should change the value to 200. Starting with Consul 1.7.1 this is the new default. @@ -688,7 +688,7 @@ Starting with Consul 1.7.1 this is the new default. ### Vault: default `http_max_conns_per_client` too low to run Vault properly -Consul 1.6.3 introduced [limiting of connections per client](/docs/agent/config/config-files#http_max_conns_per_client). The default value +Consul 1.6.3 introduced [limiting of connections per client](/consul/docs/agent/config/config-files#http_max_conns_per_client). The default value was 100, but Vault could use up to 128, which caused problems. If you want to use Vault with Consul 1.6.3 through 1.7.0, you should change the value to 200. Starting with Consul 1.7.1 this is the new default. @@ -696,10 +696,10 @@ Starting with Consul 1.7.1 this is the new default. #### Removal of Deprecated Features -Managed proxies (which have been [deprecated](/docs/connect/proxies/managed-deprecated) -since Consul 1.3.0) have now been [removed](/docs/connect/proxies). Before +Managed proxies (which have been [deprecated](/consul/docs/connect/proxies/managed-deprecated) +since Consul 1.3.0) have now been [removed](/consul/docs/connect/proxies). Before upgrading, you will need to migrate any managed proxy usage to [sidecar service -registrations](/docs/connect/registration/sidecar-service). +registrations](/consul/docs/connect/registration/sidecar-service). ## Consul 1.4.0 @@ -710,7 +710,7 @@ Connect](#connect-multi-datacenter) in the Enterprise version. ### ACL Upgrade Consul 1.4.0 includes a [new ACL -system](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) +system](/consul/tutorials/security/access-control-setup-production) that is designed to have a smooth upgrade path but requires care to upgrade components in the right order. @@ -727,14 +727,14 @@ datacenter". All configuration is backwards compatible and shouldn't need to change prior to upgrade although it's strongly recommended to migrate ACL configuration to the new syntax soon after upgrade. This includes moving to `primary_datacenter` rather than `acl_datacenter` and `acl_*` to the new [ACL -block](/docs/agent/config/config-files#acl). +block](/consul/docs/agent/config/config-files#acl). Datacenters can be upgraded in any order although secondaries will remain in [Legacy ACL mode](#legacy-acl-mode) until the primary datacenter is fully upgraded. Each datacenter should follow the [standard rolling upgrade -procedure](/docs/upgrading#standard-upgrades). +procedure](/consul/docs/upgrading#standard-upgrades). #### Legacy ACL Mode @@ -769,7 +769,7 @@ will not upgrade more than one batch per second so on a cluster with 10,000 tokens, this may take several minutes. While this is happening both old and new ACLs will work correctly with the -caveat that new ACL [Token APIs](/api-docs/acl/tokens) may not return an +caveat that new ACL [Token APIs](/consul/api-docs/acl/tokens) may not return an accessor ID for legacy tokens that are not yet migrated. #### Migrating Existing ACLs @@ -783,16 +783,16 @@ API so existing integrations that create tokens (e.g. Vault) will continue to work. The "legacy" tokens generated though will not be able to take advantage of new policy features. It's recommended that you complete migration of all tokens as soon as possible after upgrade, as well as updating any integrations to work -with the the new ACL [Token](/api-docs/acl/tokens) and -[Policy](/api-docs/acl/policies) APIs. +with the the new ACL [Token](/consul/api-docs/acl/tokens) and +[Policy](/consul/api-docs/acl/policies) APIs. -More complete details on how to upgrade "legacy" tokens is available [here](/docs/security/acl/acl-migrate-tokens). +More complete details on how to upgrade "legacy" tokens is available [here](/consul/docs/security/acl/acl-migrate-tokens). ### Connect Multi-datacenter This only applies to users upgrading from an older version of Consul Enterprise to Consul Enterprise 1.4.0 (all license types). -In addition, this upgrade will only affect clusters where [Connect is enabled](/docs/connect/configuration) on your servers before the migration. +In addition, this upgrade will only affect clusters where [Connect is enabled](/consul/docs/connect/configuration) on your servers before the migration. Connect multi-datacenter uses the same primary/secondary approach as ACLs and will use the same [primary_datacenter](#primary-datacenter). When a secondary @@ -823,7 +823,7 @@ automatically and without loss of connectivity throughout all datacenters and workloads. For more information see [Connect -Multi-datacenter](/docs/enterprise). +Multi-datacenter](/consul/docs/enterprise). ## Consul 1.3.0 @@ -846,7 +846,7 @@ The following previously deprecated fields and config options have been removed: - `CheckID` has been removed from config file check definitions (use `id` instead). - `script` has been removed from config file check definitions (use `args` instead). - `enableTagOverride` is no longer valid in service definitions (use `enable_tag_override` instead). -- The [deprecated set of metric names](/docs/upgrading/upgrade-specific#metric-names-updated) (beginning with `consul.consul.`) has been removed +- The [deprecated set of metric names](/consul/docs/upgrading/upgrade-specific#metric-names-updated) (beginning with `consul.consul.`) has been removed along with the `enable_deprecated_names` option from the metrics configuration. #### New defaults for Raft Snapshot Creation @@ -854,11 +854,11 @@ The following previously deprecated fields and config options have been removed: Consul 1.0.1 (and earlier versions of Consul) checked for raft snapshots every 5 seconds, and created new snapshots for every 8192 writes. These defaults cause constant disk IO in large busy clusters. Consul 1.1.0 increases these to larger values, -and makes them tunable via the [raft_snapshot_interval](/docs/agent/config/config-files#_raft_snapshot_interval) and -[raft_snapshot_threshold](/docs/agent/config/config-files#_raft_snapshot_threshold) parameters. We recommend +and makes them tunable via the [raft_snapshot_interval](/consul/docs/agent/config/config-files#_raft_snapshot_interval) and +[raft_snapshot_threshold](/consul/docs/agent/config/config-files#_raft_snapshot_threshold) parameters. We recommend keeping the new defaults. However, operators can go back to the old defaults by changing their -config if they prefer more frequent snapshots. See the documentation for [raft_snapshot_interval](/docs/agent/config/config-files#_raft_snapshot_interval) -and [raft_snapshot_threshold](/docs/agent/config/config-files#_raft_snapshot_threshold) to understand the trade-offs +config if they prefer more frequent snapshots. See the documentation for [raft_snapshot_interval](/consul/docs/agent/config/config-files#_raft_snapshot_interval) +and [raft_snapshot_threshold](/consul/docs/agent/config/config-files#_raft_snapshot_threshold) to understand the trade-offs when tuning these. ## Consul 1.0.7 @@ -886,10 +886,10 @@ before proceeding. #### Carefully Check and Remove Stale Servers During Rolling Upgrades Consul 1.0 (and earlier versions of Consul when running with [Raft protocol -3](/docs/agent/config/config-files#_raft_protocol) had an issue where performing +3](/consul/docs/agent/config/config-files#_raft_protocol) had an issue where performing rolling updates of Consul servers could result in an outage from old servers remaining in the cluster. -[Autopilot](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations) +[Autopilot](/consul/tutorials/datacenter-operations/autopilot-datacenter-operations) would normally remove old servers when new ones come online, but it was also waiting to promote servers to voters in pairs to maintain an odd quorum size. The pairwise promotion feature was removed so that servers become voters as @@ -897,7 +897,7 @@ soon as they are stable, allowing Autopilot to remove old servers in a safer way. When upgrading from Consul 1.0, you may need to manually -[force-leave](/commands/force-leave) old servers as part of a rolling +[force-leave](/consul/commands/force-leave) old servers as part of a rolling update to Consul 1.0.1. ## Consul 1.0 @@ -907,24 +907,24 @@ Please be sure to read over all the details here before upgrading. #### Raft Protocol Now Defaults to 3 -The [`-raft-protocol`](/docs/agent/config/cli-flags#_raft_protocol) default has +The [`-raft-protocol`](/consul/docs/agent/config/cli-flags#_raft_protocol) default has been changed from 2 to 3, enabling all -[Autopilot](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations) +[Autopilot](/consul/tutorials/datacenter-operations/autopilot-datacenter-operations) features by default. Raft protocol version 3 requires Consul running 0.8.0 or newer on all servers in order to work, so if you are upgrading with older servers in a cluster then you will need to set this back to 2 in order to upgrade. See [Raft Protocol Version -Compatibility](/docs/upgrading/upgrade-specific#raft-protocol-version-compatibility) +Compatibility](/consul/docs/upgrading/upgrade-specific#raft-protocol-version-compatibility) for more details. Also the format of `peers.json` used for outage recovery is different when running with the latest Raft protocol. Review [Manual Recovery Using -peers.json](https://learn.hashicorp.com/tutorials/consul/recovery-outage#manual-recovery-using-peers-json) +peers.json](/consul/tutorials/datacenter-operations/recovery-outage#manual-recovery-using-peers-json) for a description of the required format. Please note that the Raft protocol is different from Consul's internal protocol -as described on the [Protocol Compatibility Promise](/docs/upgrading/compatibility) +as described on the [Protocol Compatibility Promise](/consul/docs/upgrading/compatibility) page, and as is shown in commands like `consul members` and `consul version`. To see the version of the Raft protocol in use on each server, use the `consul operator raft list-peers` command. @@ -936,14 +936,14 @@ servers, and then slowly stand down each of the older servers in a similar fashion. When using Raft protocol version 3, servers are identified by their -[`-node-id`](/docs/agent/config/cli-flags#_node_id) instead of their IP address +[`-node-id`](/consul/docs/agent/config/cli-flags#_node_id) instead of their IP address when Consul makes changes to its internal Raft quorum configuration. This means that once a cluster has been upgraded with servers all running Raft protocol version 3, it will no longer allow servers running any older Raft protocol versions to be added. If running a single Consul server, restarting it in-place will result in that server not being able to elect itself as a leader. To avoid this, either set the Raft protocol back to 2, or use [Manual Recovery Using -peers.json](https://learn.hashicorp.com/tutorials/consul/recovery-outage#manual-recovery-using-peers-json) +peers.json](/consul/tutorials/datacenter-operations/recovery-outage#manual-recovery-using-peers-json) to map the server to its node ID in the Raft quorum configuration. #### Config Files Require an Extension @@ -951,14 +951,14 @@ to map the server to its node ID in the Raft quorum configuration. As part of supporting the [HCL](https://github.com/hashicorp/hcl#syntax) format for Consul's config files, an `.hcl` or `.json` extension is required for all config files loaded by Consul, even when using the -[`-config-file`](/docs/agent/config/cli-flags#_config_file) argument to specify a +[`-config-file`](/consul/docs/agent/config/cli-flags#_config_file) argument to specify a file directly. #### Service Definition Parameter Case changed All config file formats now require snake_case fields, so all CamelCased parameter names should be changed before upgrading. -See [Service Definition Parameter Case](/docs/discovery/services#service-definition-parameter-case) documentation for details. +See [Service Definition Parameter Case](/consul/docs/discovery/services#service-definition-parameter-case) documentation for details. #### Deprecated Options Have Been Removed @@ -968,41 +968,41 @@ upgrading. Here's the complete list of removed options and their equivalents: | Removed Option | Equivalent | | ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `-dc` | [`-datacenter`](/docs/agent/config/cli-flags#_datacenter) | -| `-retry-join-azure-tag-name` | [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) | -| `-retry-join-azure-tag-value` | [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) | -| `-retry-join-ec2-region` | [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) | -| `-retry-join-ec2-tag-key` | [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) | -| `-retry-join-ec2-tag-value` | [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) | -| `-retry-join-gce-credentials-file` | [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) | -| `-retry-join-gce-project-name` | [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) | -| `-retry-join-gce-tag-name` | [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) | -| `-retry-join-gce-zone-pattern` | [`-retry-join`](/docs/agent/config/cli-flags#_retry_join) | +| `-dc` | [`-datacenter`](/consul/docs/agent/config/cli-flags#_datacenter) | +| `-retry-join-azure-tag-name` | [`-retry-join`](/consul/docs/agent/config/cli-flags#_retry_join) | +| `-retry-join-azure-tag-value` | [`-retry-join`](/consul/docs/agent/config/cli-flags#_retry_join) | +| `-retry-join-ec2-region` | [`-retry-join`](/consul/docs/agent/config/cli-flags#_retry_join) | +| `-retry-join-ec2-tag-key` | [`-retry-join`](/consul/docs/agent/config/cli-flags#_retry_join) | +| `-retry-join-ec2-tag-value` | [`-retry-join`](/consul/docs/agent/config/cli-flags#_retry_join) | +| `-retry-join-gce-credentials-file` | [`-retry-join`](/consul/docs/agent/config/cli-flags#_retry_join) | +| `-retry-join-gce-project-name` | [`-retry-join`](/consul/docs/agent/config/cli-flags#_retry_join) | +| `-retry-join-gce-tag-name` | [`-retry-join`](/consul/docs/agent/config/cli-flags#_retry_join) | +| `-retry-join-gce-zone-pattern` | [`-retry-join`](/consul/docs/agent/config/cli-flags#_retry_join) | | `addresses.rpc` | None, the RPC server for CLI commands is no longer supported. | -| `advertise_addrs` | [`ports`](/docs/agent/config/config-files#ports) with [`advertise_addr`](/docs/agent/config/config-files#advertise_addr) and/or [`advertise_addr_wan`](/docs/agent/config/config-files#advertise_addr_wan) | -| `dogstatsd_addr` | [`telemetry.dogstatsd_addr`](/docs/agent/config/config-files#telemetry-dogstatsd_addr) | -| `dogstatsd_tags` | [`telemetry.dogstatsd_tags`](/docs/agent/config/config-files#telemetry-dogstatsd_tags) | -| `http_api_response_headers` | [`http_config.response_headers`](/docs/agent/config/config-files#response_headers) | +| `advertise_addrs` | [`ports`](/consul/docs/agent/config/config-files#ports) with [`advertise_addr`](/consul/docs/agent/config/config-files#advertise_addr) and/or [`advertise_addr_wan`](/consul/docs/agent/config/config-files#advertise_addr_wan) | +| `dogstatsd_addr` | [`telemetry.dogstatsd_addr`](/consul/docs/agent/config/config-files#telemetry-dogstatsd_addr) | +| `dogstatsd_tags` | [`telemetry.dogstatsd_tags`](/consul/docs/agent/config/config-files#telemetry-dogstatsd_tags) | +| `http_api_response_headers` | [`http_config.response_headers`](/consul/docs/agent/config/config-files#response_headers) | | `ports.rpc` | None, the RPC server for CLI commands is no longer supported. | -| `recursor` | [`recursors`](/docs/agent/config/config-files#recursors) | -| `retry_join_azure` | [`retry-join`](/docs/agent/config/config-files#retry_join) | -| `retry_join_ec2` | [`retry-join`](/docs/agent/config/config-files#retry_join) | -| `retry_join_gce` | [`retry-join`](/docs/agent/config/config-files#retry_join) | -| `statsd_addr` | [`telemetry.statsd_address`](/docs/agent/config/config-files#telemetry-statsd_address) | -| `statsite_addr` | [`telemetry.statsite_address`](/docs/agent/config/config-files#telemetry-statsite_address) | -| `statsite_prefix` | [`telemetry.metrics_prefix`](/docs/agent/config/config-files#telemetry-metrics_prefix) | -| `telemetry.statsite_prefix` | [`telemetry.metrics_prefix`](/docs/agent/config/config-files#telemetry-metrics_prefix) | -| (service definitions) `serviceid` | [`id`](/api-docs/agent/service#id) | -| (service definitions) `dockercontainerid` | [`docker_container_id`](/api-docs/agent/check#dockercontainerid) | -| (service definitions) `tlsskipverify` | [`tls_skip_verify`](/api-docs/agent/check#tlsskipverify) | -| (service definitions) `deregistercriticalserviceafter` | [`deregister_critical_service_after`](/api-docs/agent/check#deregistercriticalserviceafter) | +| `recursor` | [`recursors`](/consul/docs/agent/config/config-files#recursors) | +| `retry_join_azure` | [`retry-join`](/consul/docs/agent/config/config-files#retry_join) | +| `retry_join_ec2` | [`retry-join`](/consul/docs/agent/config/config-files#retry_join) | +| `retry_join_gce` | [`retry-join`](/consul/docs/agent/config/config-files#retry_join) | +| `statsd_addr` | [`telemetry.statsd_address`](/consul/docs/agent/config/config-files#telemetry-statsd_address) | +| `statsite_addr` | [`telemetry.statsite_address`](/consul/docs/agent/config/config-files#telemetry-statsite_address) | +| `statsite_prefix` | [`telemetry.metrics_prefix`](/consul/docs/agent/config/config-files#telemetry-metrics_prefix) | +| `telemetry.statsite_prefix` | [`telemetry.metrics_prefix`](/consul/docs/agent/config/config-files#telemetry-metrics_prefix) | +| (service definitions) `serviceid` | [`id`](/consul/api-docs/agent/service#id) | +| (service definitions) `dockercontainerid` | [`docker_container_id`](/consul/api-docs/agent/check#dockercontainerid) | +| (service definitions) `tlsskipverify` | [`tls_skip_verify`](/consul/api-docs/agent/check#tlsskipverify) | +| (service definitions) `deregistercriticalserviceafter` | [`deregister_critical_service_after`](/consul/api-docs/agent/check#deregistercriticalserviceafter) | #### `statsite_prefix` Renamed to `metrics_prefix` Since the `statsite_prefix` configuration option applied to all telemetry providers, `statsite_prefix` was renamed to -[`metrics_prefix`](/docs/agent/config/config-files#telemetry-metrics_prefix). +[`metrics_prefix`](/consul/docs/agent/config/config-files#telemetry-metrics_prefix). Configuration files will need to be updated when upgrading to this version of Consul. @@ -1014,8 +1014,8 @@ wrongly stated that you could configure both host and port. #### Escaping Behavior Changed for go-discover Configs -The format for [`-retry-join`](/docs/agent/config/cli-flags#retry-join) and -[`-retry-join-wan`](/docs/agent/config/cli-flags#retry-join-wan) values that use +The format for [`-retry-join`](/consul/docs/agent/config/cli-flags#retry-join) and +[`-retry-join-wan`](/consul/docs/agent/config/cli-flags#retry-join-wan) values that use [go-discover](https://github.com/hashicorp/go-discover) cloud auto joining has changed. Values in `key=val` sequences must no longer be URL encoded and can be provided as literals as long as they do not contain spaces, backslashes `\` or @@ -1085,7 +1085,7 @@ directly returning one of Consul's internal data structures. This configuration structure has been moved under `DebugConfig`, and is documents as for debugging use and subject to change, and a small set of elements of `Config` have been maintained and documented. See [Read -Configuration](/api-docs/agent#read-configuration) endpoint documentation for +Configuration](/consul/api-docs/agent#read-configuration) endpoint documentation for details. #### Deprecated `configtest` Command Removed @@ -1133,7 +1133,7 @@ invalid health checks would get skipped. #### Script Checks Are Now Opt-In -A new [`enable_script_checks`](/docs/agent/config/cli-flags#_enable_script_checks) +A new [`enable_script_checks`](/consul/docs/agent/config/cli-flags#_enable_script_checks) configuration option was added, and defaults to `false`, meaning that in order to allow an agent to run health checks that execute scripts, this will need to be configured and set to `true`. This provides a safer out-of-the-box @@ -1142,7 +1142,7 @@ health checks. If your cluster uses script health checks please be sure to set this to `true` as part of upgrading agents. If this is set to `true`, you should also enable -[ACLs](https://learn.hashicorp.com/tutorials/consul/access-control-setup-production) +[ACLs](/consul/tutorials/security/access-control-setup-production) to provide control over which users are allowed to register health checks that could potentially execute scripts on the agent machines. @@ -1155,10 +1155,10 @@ for more information. Consul releases will no longer include a `web_ui.zip` file with the compiled web assets. These have been built in to the Consul binary since the 0.7.x -series and can be enabled with the [`-ui`](/docs/agent/config/cli-flags#_ui) +series and can be enabled with the [`-ui`](/consul/docs/agent/config/cli-flags#_ui) configuration option. These built-in web assets have always been identical to the contents of the `web_ui.zip` file for each release. The -[`-ui-dir`](/docs/agent/config/cli-flags#_ui_dir) option is still available for +[`-ui-dir`](/consul/docs/agent/config/cli-flags#_ui_dir) option is still available for hosting customized versions of the web assets, but the vast majority of Consul users can just use the built in web assets. @@ -1190,12 +1190,12 @@ to the following commands: #### Version 8 ACLs Are Now Opt-Out -The [`acl_enforce_version_8`](/docs/agent/config/config-files#acl_enforce_version_8) +The [`acl_enforce_version_8`](/consul/docs/agent/config/config-files#acl_enforce_version_8) configuration now defaults to `true` to enable full version 8 ACL support by default. If you are upgrading an existing cluster with ACLs enabled, you will need to set this to `false` during the upgrade on **both Consul agents and Consul servers**. Version 8 ACLs were also changed so that -[`acl_datacenter`](/docs/agent/config/config-files#acl_datacenter) must be set on +[`acl_datacenter`](/consul/docs/agent/config/config-files#acl_datacenter) must be set on agents in order to enable the agent-side enforcement of ACLs. This makes for a smoother experience in clusters where ACLs aren't enabled at all, but where the agents would have to wait to contact a Consul server before learning that. @@ -1203,14 +1203,14 @@ agents would have to wait to contact a Consul server before learning that. #### Remote Exec Is Now Opt-In The default for -[`disable_remote_exec`](/docs/agent/config/config-files#disable_remote_exec) was +[`disable_remote_exec`](/consul/docs/agent/config/config-files#disable_remote_exec) was changed to "true", so now operators need to opt-in to having agents support -running commands remotely via [`consul exec`](/commands/exec). +running commands remotely via [`consul exec`](/consul/commands/exec). #### Raft Protocol Version Compatibility When upgrading to Consul 0.8.0 from a version lower than 0.7.0, users will need -to set the [`-raft-protocol`](/docs/agent/config/cli-flags#_raft_protocol) option +to set the [`-raft-protocol`](/consul/docs/agent/config/cli-flags#_raft_protocol) option to 1 in order to maintain backwards compatibility with the old servers during the upgrade. After the servers have been migrated to version 0.8.0, `-raft-protocol` can be moved up to 2 and the servers restarted to match the @@ -1227,7 +1227,7 @@ table of the Raft Protocol versions supported by each Consul version: | 0.8 | 1, 2, 3 | In order to enable all -[Autopilot](https://learn.hashicorp.com/tutorials/consul/autopilot-datacenter-operations) +[Autopilot](/consul/tutorials/datacenter-operations/autopilot-datacenter-operations) features, all servers in a Consul datacenter must be running with Raft protocol version 3 or later. @@ -1245,7 +1245,7 @@ process to reap child processes. #### DNS Resiliency Defaults -The default for [`max_stale`](/docs/agent/config/config-files#max_stale) has been +The default for [`max_stale`](/consul/docs/agent/config/config-files#max_stale) has been increased from 5 seconds to a near-indefinite threshold (10 years) to allow DNS queries to continue to be served in the event of a long outage with no leader. A new telemetry counter was added at `consul.dns.stale_queries` to track when @@ -1259,7 +1259,7 @@ to be aware of during an upgrade are categorized below. #### Performance Timing Defaults and Tuning Consul 0.7 now defaults the DNS configuration to allow for stale queries by -defaulting [`allow_stale`](/docs/agent/config/config-files#allow_stale) to true for +defaulting [`allow_stale`](/consul/docs/agent/config/config-files#allow_stale) to true for better utilization of available servers. If you want to retain the previous behavior, set the following configuration: @@ -1272,9 +1272,9 @@ behavior, set the following configuration: ``` Consul also 0.7 introduced support for tuning Raft performance using a new -[performance configuration block](/docs/agent/config/config-files#performance). Also, +[performance configuration block](/consul/docs/agent/config/config-files#performance). Also, the default Raft timing is set to a lower-performance mode suitable for -[minimal Consul servers](/docs/install/performance#minimum). +[minimal Consul servers](/consul/docs/install/performance#minimum). To continue to use the high-performance settings that were the default prior to Consul 0.7 (recommended for production servers), add the following @@ -1288,12 +1288,12 @@ configuration to all Consul servers when upgrading: } ``` -See the [Server Performance](/docs/install/performance) guide for more details. +See the [Server Performance](/consul/docs/install/performance) guide for more details. #### Leave-Related Configuration Defaults -The default behavior of [`leave_on_terminate`](/docs/agent/config/config-files#leave_on_terminate) -and [`skip_leave_on_interrupt`](/docs/agent/config/config-files#skip_leave_on_interrupt) +The default behavior of [`leave_on_terminate`](/consul/docs/agent/config/config-files#leave_on_terminate) +and [`skip_leave_on_interrupt`](/consul/docs/agent/config/config-files#skip_leave_on_interrupt) are now dependent on whether or not the agent is acting as a server or client: - For servers, `leave_on_terminate` defaults to "false" and `skip_leave_on_interrupt` @@ -1317,7 +1317,7 @@ to upgrade all agents to a newer version of Consul before upgrading to Consul #### Prepared Query Changes Consul version 0.7 adds a feature which allows prepared queries to store a -[`Near` parameter](/api-docs/query#near) in the query definition +[`Near` parameter](/consul/api-docs/query#near) in the query definition itself. This feature enables using the distance sorting features of prepared queries without explicitly providing the node to sort near in requests, but requires the agent servicing a request to send additional information about @@ -1332,12 +1332,12 @@ using this feature. #### WAN Address Translation in HTTP Endpoints Consul version 0.7 added support for translating WAN addresses in certain -[HTTP endpoints](/docs/agent/config/config-files#translate_wan_addrs). The servers +[HTTP endpoints](/consul/docs/agent/config/config-files#translate_wan_addrs). The servers and the agents need to be running version 0.7 or later in order to use this feature. These translated addresses could break HTTP endpoint consumers that are -expecting local addresses, so a new [`X-Consul-Translate-Addresses`](/api-docs/api-structure#translated-addresses) +expecting local addresses, so a new [`X-Consul-Translate-Addresses`](/consul/api-docs/api-structure#translated-addresses) header was added to allow clients to detect if translation is enabled for HTTP responses. A "lan" tag was added to `TaggedAddresses` for clients that need the local address regardless of translation. @@ -1350,7 +1350,7 @@ the file. Consul 0.7 also uses a new, automatically-created raft/peers.info file to avoid ingesting the `peers.json` file on the first start after upgrading (the `peers.json` file is simply deleted on the first start after upgrading). -Please be sure to review the [Outage Recovery tutorial](https://learn.hashicorp.com/tutorials/consul/recovery-outage) +Please be sure to review the [Outage Recovery tutorial](/consul/tutorials/datacenter-operations/recovery-outage) before upgrading for more details. ## Consul 0.6.4 @@ -1363,7 +1363,7 @@ require any ACL to manage them, and prepared queries with a `Name` defined are now governed by a new `query` ACL policy that will need to be configured after the upgrade. -See the [ACL rules documentation](/docs/security/acl/acl-rules#prepared-query-rules) for more details +See the [ACL rules documentation](/consul/docs/security/acl/acl-rules#prepared-query-rules) for more details about the new behavior and how it compares to previous versions of Consul. ## Consul 0.6 @@ -1414,7 +1414,7 @@ which require it: } When the DNS interface is queried, the agent's -[`acl_token`](/docs/agent/config/config-files#acl_token) is used, so be sure +[`acl_token`](/consul/docs/agent/config/config-files#acl_token) is used, so be sure that token has sufficient privileges to return the DNS records you expect to retrieve from it. @@ -1471,7 +1471,7 @@ this: This automatic upgrade will only exist in Consul 0.5.1+ and it will be removed starting with Consul 0.6.0+. It will still be possible to upgrade directly from pre-0.5.1 versions by using the consul-migrate utility, which is available on the -[Consul Tools page](/docs/integrate/download-tools). +[Consul Tools page](/consul/docs/integrate/download-tools). ## Consul 0.5 diff --git a/website/content/partials/http_api_and_cli_characteristics_links.mdx b/website/content/partials/http_api_and_cli_characteristics_links.mdx index 0cbb237023..85534c56d9 100644 --- a/website/content/partials/http_api_and_cli_characteristics_links.mdx +++ b/website/content/partials/http_api_and_cli_characteristics_links.mdx @@ -1,6 +1,6 @@ -[Required ACLs]: /docs/security/acl -[Blocking queries]: /api-docs/features/blocking -[Consistency modes]: /api-docs/features/consistency -[Agent caching]: /api-docs/features/caching +[Required ACLs]: /consul/docs/security/acl +[Blocking queries]: /consul/api-docs/features/blocking +[Consistency modes]: /consul/api-docs/features/consistency +[Agent caching]: /consul/api-docs/features/caching diff --git a/website/content/partials/http_api_options_client.mdx b/website/content/partials/http_api_options_client.mdx index 472c250e66..32ac263339 100644 --- a/website/content/partials/http_api_options_client.mdx +++ b/website/content/partials/http_api_options_client.mdx @@ -20,7 +20,7 @@ used instead. The scheme can also be set to HTTPS by setting the environment variable `CONSUL_HTTP_SSL=true`. This may be a unix domain socket using `unix:///path/to/socket` if the [agent is configured to - listen](/docs/agent/config/config-files#addresses) that way. + listen](/consul/docs/agent/config/config-files#addresses) that way. - `-tls-server-name=` - The server name to use as the SNI host when connecting via TLS. This can also be specified via the `CONSUL_TLS_SERVER_NAME` diff --git a/website/content/partials/http_api_results_filtered_by_acls.mdx b/website/content/partials/http_api_results_filtered_by_acls.mdx index fda2b97446..8e951c4066 100644 --- a/website/content/partials/http_api_results_filtered_by_acls.mdx +++ b/website/content/partials/http_api_results_filtered_by_acls.mdx @@ -1,3 +1,3 @@ The HTTP response includes the `X-Consul-Results-Filtered-By-ACLs: true` header if the response array excludes results due to ACL policy configuration. -Refer to the [HTTP API documentation](/api-docs/api-structure#results-filtered-by-acls) for more information. +Refer to the [HTTP API documentation](/consul/api-docs/api-structure#results-filtered-by-acls) for more information.