From 5baa231eb00a7f9610298264e5194232e819b247 Mon Sep 17 00:00:00 2001 From: Blake Covarrubias Date: Mon, 2 Aug 2021 11:55:23 -0700 Subject: [PATCH] docs: Add namespace parameter to additional HTTP endpoints (#10731) Document the namespace parameter can be specified on HTTP Check, Connect CA leaf, and Discovery Chain API endpoints. Co-authored-by: Freddy --- website/content/api-docs/agent/check.mdx | 57 ++++++++++++++++++-- website/content/api-docs/agent/connect.mdx | 7 +++ website/content/api-docs/discovery-chain.mdx | 6 +++ 3 files changed, 67 insertions(+), 3 deletions(-) diff --git a/website/content/api-docs/agent/check.mdx b/website/content/api-docs/agent/check.mdx index e332a435e..0af557663 100644 --- a/website/content/api-docs/agent/check.mdx +++ b/website/content/api-docs/agent/check.mdx @@ -40,6 +40,12 @@ The table below shows this endpoint's support for - `filter` `(string: "")` - Specifies the expression used to filter the queries results prior to returning the data. +- `ns` `(string: "")` - Specifies the namespace in + which to list checks. This value can be specified as the `ns` URL query + parameter or the `X-Consul-Namespace` header. If not provided by either, + the namespace will be inherited from the request's ACL token or will default + to the `default` namespace. Added in Consul 1.7.0. + ### Sample Request ```shell-session @@ -60,7 +66,13 @@ $ curl \ "Output": "", "ServiceID": "redis", "ServiceName": "redis", - "ServiceTags": ["primary"] + "ServiceTags": ["primary"], + "Type": "tcp", + "ExposedPort": 0, + "Definition": {}, + "Namespace": "default", + "CreateIndex": 0, + "ModifyIndex": 0 } } ``` @@ -110,6 +122,13 @@ The table below shows this endpoint's support for This defaults to the `"Name"` parameter, but it may be necessary to provide an ID for uniqueness. This value will return in the response as `"CheckId"`. +- `Namespace` `(string: "")` - Specifies the namespace in + which to register the check. This parameter is only valid for service checks. + If not provided in the JSON body, the value of the `ns` URL query parameter or + in the `X-Consul-Namespace` header will be used. If not provided by either, + the namespace will be inherited from the request's ACL token or will default + to the `default` namespace. Added in Consul 1.7.0. + - `Interval` `(string: "")` - Specifies the frequency at which to run this check. This is required for HTTP and TCP checks. @@ -208,8 +227,9 @@ The table below shows this endpoint's support for made to both addresses, and the first successful connection attempt will result in a successful check. -- `TTL` `(string: "")` - Specifies this is a TTL check, and the TTL endpoint - must be used periodically to update the state of the check. +- `TTL` `(duration: 10s)` - Specifies this is a TTL check, and the TTL endpoint + must be used periodically to update the state of the check. If the check is not + set to passing within the specified duration, then the check will be set to the failed state. - `ServiceID` `(string: "")` - Specifies the ID of a service to associate the registered check with an existing service provided by the agent. @@ -230,6 +250,7 @@ The table below shows this endpoint's support for { "ID": "mem", "Name": "Memory utilization", + "Namespace": "default", "Notes": "Ensure we don't oversubscribe memory", "DeregisterCriticalServiceAfter": "90m", "Args": ["/usr/local/bin/check_mem.py"], @@ -280,6 +301,12 @@ The table below shows this endpoint's support for - `check_id` `(string: "")` - Specifies the unique ID of the check to deregister. This is specified as part of the URL. +- `ns` `(string: "")` - Specifies the namespace in + which to deregister the check. This value can be specified as the `ns` URL query + parameter or the `X-Consul-Namespace` header. If not provided by either, + the namespace will be inherited from the request's ACL token or will default + to the `default` namespace. Added in Consul 1.7.0. + ### Sample Request ```shell-session @@ -315,6 +342,12 @@ The table below shows this endpoint's support for - `note` `(string: "")` - Specifies a human-readable message. This will be passed through to the check's `Output` field. +- `ns` `(string: "")` - Specifies the namespace in + which to update the check. This value can be specified as the `ns` URL query + parameter or the `X-Consul-Namespace` header. If not provided by either, + the namespace will be inherited from the request's ACL token or will default + to the `default` namespace. Added in Consul 1.7.0. + ### Sample Request ```shell-session @@ -350,6 +383,12 @@ The table below shows this endpoint's support for - `note` `(string: "")` - Specifies a human-readable message. This will be passed through to the check's `Output` field. +- `ns` `(string: "")` - Specifies the namespace in + which to update the check. This value can be specified as the `ns` URL query + parameter or the `X-Consul-Namespace` header. If not provided by either, + the namespace will be inherited from the request's ACL token or will default + to the `default` namespace. Added in Consul 1.7.0. + ### Sample Request ```shell-session @@ -384,6 +423,12 @@ The table below shows this endpoint's support for - `note` `(string: "")` - Specifies a human-readable message. This will be passed through to the check's `Output` field. +- `ns` `(string: "")` - Specifies the namespace in + which to update the check. This value can be specified as the `ns` URL query + parameter or the `X-Consul-Namespace` header. If not provided by either, + the namespace will be inherited from the request's ACL token or will default + to the `default` namespace. Added in Consul 1.7.0. + ### Sample Request ```shell-session @@ -421,6 +466,12 @@ The table below shows this endpoint's support for - `Output` `(string: "")` - Specifies a human-readable message. This will be passed through to the check's `Output` field. +- `ns` `(string: "")` - Specifies the namespace in + which to update the check. This value can be specified as the `ns` URL query + parameter or the `X-Consul-Namespace` header. If not provided by either, + the namespace will be inherited from the request's ACL token or will default + to the `default` namespace. Added in Consul 1.7.0. + ### Sample Payload ```json diff --git a/website/content/api-docs/agent/connect.mdx b/website/content/api-docs/agent/connect.mdx index e319c6031..2e31ac125 100644 --- a/website/content/api-docs/agent/connect.mdx +++ b/website/content/api-docs/agent/connect.mdx @@ -194,6 +194,12 @@ The table below shows this endpoint's support for certificate. This is specified in the URL. The service does not need to exist in the catalog, but the proper ACL permissions must be available. +- `ns` `(string: "")` - Specifies the namespace in + which to request the leaf certificate. This value can be specified as the `ns` + URL query parameter or the `X-Consul-Namespace` header. If not provided by either, + the namespace will be inherited from the request's ACL token or will default + to the `default` namespace. Added in Consul 1.7.0. + ### Sample Request ```shell-session @@ -212,6 +218,7 @@ $ curl \ "ServiceURI": "spiffe://11111111-2222-3333-4444-555555555555.consul/ns/default/dc/dc1/svc/web", "ValidAfter": "2018-05-21T16:33:28Z", "ValidBefore": "2018-05-24T16:33:28Z", + "Namespace": "default", "CreateIndex": 5, "ModifyIndex": 5 } diff --git a/website/content/api-docs/discovery-chain.mdx b/website/content/api-docs/discovery-chain.mdx index 909a1d605..bc1d1b00b 100644 --- a/website/content/api-docs/discovery-chain.mdx +++ b/website/content/api-docs/discovery-chain.mdx @@ -61,6 +61,12 @@ The table below shows this endpoint's support for [`datacenter`](/docs/connect/registration/service-registration#datacenter) parameter. +- `ns` `(string: "")` - Specifies the source namespace + to use as the basis of compilation. This value can be specified as the `ns` + URL query parameter or the `X-Consul-Namespace` header. If not provided by either, + the namespace will be inherited from the request's ACL token or will default + to the `default` namespace. Added in Consul 1.7.0. + ### POST Body Parameters - `OverrideConnectTimeout` `(duration: 0s)` - Overrides the final [connect