From bc42074f5752f1261afc6a5ae3f3a156ab95f78b Mon Sep 17 00:00:00 2001 From: Blake Covarrubias Date: Tue, 5 Nov 2019 20:34:46 -0800 Subject: [PATCH] docs: Miscellaneous docs cleanup (#6742) Fix spelling errors, API doc inconsistencies, and formatting issues. * Fix several spelling errors. * Prepend / to v1/event/list path in Watches. * Rename script handlers to match Watch type. * Remove /v1 path prefix on service health API endpoints. Makes request path consistent with the rest of the HTTP API documentation which does not include the /v1 prefix. * Fix bracket formatting issue on Telemetry page. The HTML codes used for brackets inside of the code block are not interpolated, and are shown as literal strings. Replace the numeric HTML codes with the intended character value to fix display formatting. Also placed variable reference on agent/options.html inside code block for consistency with the presentation of other options on the page. * Add missing word to Coordinate.Node docstring. Resolves #6014 --- api/coordinate.go | 2 +- website/source/api/acl/acl.html.md | 2 +- website/source/api/agent/service.html.md | 22 +++++++++---------- website/source/api/catalog.html.md | 2 +- website/source/api/features/caching.html.md | 2 +- website/source/api/query.html.md | 2 +- .../source/docs/agent/cloud-auto-join.html.md | 2 +- website/source/docs/agent/options.html.md | 2 +- website/source/docs/agent/telemetry.html.md | 2 +- website/source/docs/agent/watches.html.md | 8 +++---- .../docs/connect/connect-internals.html.md | 2 +- .../registration/service-registration.html.md | 2 +- .../source/docs/platform/k8s/index.html.md | 2 +- .../docs/platform/k8s/service-sync.html.md | 2 +- 14 files changed, 27 insertions(+), 27 deletions(-) diff --git a/api/coordinate.go b/api/coordinate.go index 53318f11d..776630f67 100644 --- a/api/coordinate.go +++ b/api/coordinate.go @@ -84,7 +84,7 @@ func (c *Coordinate) Update(coord *CoordinateEntry, q *WriteOptions) (*WriteMeta return wm, nil } -// Node is used to return the coordinates of a single in the LAN pool. +// Node is used to return the coordinates of a single node in the LAN pool. func (c *Coordinate) Node(node string, q *QueryOptions) ([]*CoordinateEntry, *QueryMeta, error) { r := c.c.newRequest("GET", "/v1/coordinate/node/"+node) r.setQueryOptions(q) diff --git a/website/source/api/acl/acl.html.md b/website/source/api/acl/acl.html.md index 414ded40e..205bdb7dd 100644 --- a/website/source/api/acl/acl.html.md +++ b/website/source/api/acl/acl.html.md @@ -159,7 +159,7 @@ $ curl \ returned by the [`/v1/acl/list`](/api/acl/legacy.html#acl_list) 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/polcies`](/api/acl/policies.html#list-policies) + `X-Consul-Index` header returned by the [`/v1/acl/policies`](/api/acl/policies.html#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. diff --git a/website/source/api/agent/service.html.md b/website/source/api/agent/service.html.md index 819e7726a..9f264a8f4 100644 --- a/website/source/api/agent/service.html.md +++ b/website/source/api/agent/service.html.md @@ -222,10 +222,10 @@ default. In order to get the text format, you can append `?format=text` to the URL or use Mime Content negotiation by specifying a HTTP Header `Accept` starting with `text/plain`. -| Method | Path | Produces | -| ------ | --------------------------------------------------------- | ------------------ | -| `GET` | `/v1/agent/health/service/name/:service_name` | `application/json` | -| `GET` | `/v1/agent/health/service/name/:service_name?format=text` | `text/plain` | +| Method | Path | Produces | +| ------ | ------------------------------------------------------ | ------------------ | +| `GET` | `/agent/health/service/name/:service_name` | `application/json` | +| `GET` | `/agent/health/service/name/:service_name?format=text` | `text/plain` | The table below shows this endpoint's support for [blocking queries](/api/features/blocking.html), @@ -248,7 +248,7 @@ service instance(s) and will return the corresponding HTTP codes: | `429` | Some healthchecks are passing, at least one is warning | | `503` | At least one of the healthchecks is critical | -Those endpoints might be usefull for the following use-cases: +Those endpoints might be useful for the following use-cases: * a load-balancer wants to check IP connectivity with an agent and retrieve the aggregated status of given service @@ -447,14 +447,14 @@ curl localhost:8500/v1/agent/health/service/id/web1 ## Get local service health by its ID -Retrive an aggregated state of service(s) on the local agent by ID. +Retrieve an aggregated state of service(s) on the local agent by ID. See: -| Method | Path | Produces | -| ------ | ------------------------------------------------------ | ------------------ | -| `GET` | `/v1/agent/health/service/id/:service_id` | `application/json` | -| `GET` | `/v1/agent/health/service/id/:service_id?format=text` | `text/plain` | +| Method | Path | Produces | +| ------ | -------------------------------------------------- | ------------------ | +| `GET` | `/agent/health/service/id/:service_id` | `application/json` | +| `GET` | `/agent/health/service/id/:service_id?format=text` | `text/plain` | Parameters and response format are the same as [`/v1/agent/health/service/name/:service_name`](/api/agent/service.html#get-local-service-health). @@ -487,7 +487,7 @@ The table below shows this endpoint's support for ### Query string parameters -- `replace-existing-checks` - Missing healthchecks from the request will be deleted from the agent. Using this parameter allows to idempotently register a service and its checks whithout having to manually deregister checks. +- `replace-existing-checks` - Missing healthchecks from the request will be deleted from the agent. Using this parameter allows to idempotently register a service and its checks without having to manually deregister checks. ### Parameters diff --git a/website/source/api/catalog.html.md b/website/source/api/catalog.html.md index 83f911975..411bfcb09 100644 --- a/website/source/api/catalog.html.md +++ b/website/source/api/catalog.html.md @@ -83,7 +83,7 @@ The table below shows this endpoint's support for only a health check or service entry on a node needs to be updated or when a register request is intended to update a service entry or health check. In both use cases, node information will not be overwritten, if the node is - already registered. Note, if the paramater is enabled for a node that doesn't + already registered. Note, if the parameter is enabled for a node that doesn't exist, it will still be created. It is important to note that `Check` does not have to be provided with `Service` diff --git a/website/source/api/features/caching.html.md b/website/source/api/features/caching.html.md index 261835d1e..1f1f9705e 100644 --- a/website/source/api/features/caching.html.md +++ b/website/source/api/features/caching.html.md @@ -91,7 +91,7 @@ In all cases the HTTP `X-Cache` header is always set in the response to either For cache hits, the HTTP `Age` header is always set in the response to indicate how many seconds since that response was fetched from the servers. As long as the local agent has an active connection to the servers, the age will always be -`0` since the value is up-to-date. If the agent get's disconnected, the cached +`0` since the value is up-to-date. If the agent gets disconnected, the cached result is still returned but with an `Age` that indicates how many seconds have elapsed since the local agent got disconnected from the servers, during which time updates to the result might have been missed. diff --git a/website/source/api/query.html.md b/website/source/api/query.html.md index 7387deace..d422a7185 100644 --- a/website/source/api/query.html.md +++ b/website/source/api/query.html.md @@ -223,7 +223,7 @@ The table below shows this endpoint's support for where the query was executed from. For HTTP the source IP is the remote peer's IP address or the value of the X-Forwarded-For header with the header taking precedence. For DNS the source IP is the remote peer's IP - address or the value of the ENDS client IP with the EDNS client IP + address or the value of the EDNS client IP with the EDNS client IP taking precedence. diff --git a/website/source/docs/agent/cloud-auto-join.html.md b/website/source/docs/agent/cloud-auto-join.html.md index 67664c45c..c13d753c8 100644 --- a/website/source/docs/agent/cloud-auto-join.html.md +++ b/website/source/docs/agent/cloud-auto-join.html.md @@ -100,7 +100,7 @@ $ consul agent -retry-join "provider=azure tag_name=... tag_value=... tenant_id= - `provider` (required) - the name of the provider ("azure" in this case). - `tenant_id` (required) - the tenant to join machines in. - `client_id` (required) - the client to authenticate with. -- `secret_access_key` (required) - the secret client key. **NOTE** This value often may have an equals sign in it's value, especially if generated from the Azure Portal, so is important to wrap in single quotes eg. `secret_acccess_key='fpOfcHQJAQBczjAxiVpeyLmX1M0M0KPBST+GU2GvEN4='` +- `secret_access_key` (required) - the secret client key. **NOTE** This value often may have an equals sign in it's value, especially if generated from the Azure Portal, so is important to wrap in single quotes eg. `secret_access_key='fpOfcHQJAQBczjAxiVpeyLmX1M0M0KPBST+GU2GvEN4='` Variables can also be provided by environmental variables: diff --git a/website/source/docs/agent/options.html.md b/website/source/docs/agent/options.html.md index 9f94a44fb..9bef97e78 100644 --- a/website/source/docs/agent/options.html.md +++ b/website/source/docs/agent/options.html.md @@ -1806,7 +1806,7 @@ to the old fragment --> * `verify_server_hostname` - If set to true, Consul verifies for all outgoing TLS connections that the TLS certificate - presented by the servers matches "server.<datacenter>.<domain>" + presented by the servers matches `server..` hostname. By default, this is false, and Consul does not verify the hostname of the certificate, only that it is signed by a trusted CA. This setting is _critical_ to prevent a compromised client from being restarted as a server diff --git a/website/source/docs/agent/telemetry.html.md b/website/source/docs/agent/telemetry.html.md index 7c7158ef5..7bb420eb3 100644 --- a/website/source/docs/agent/telemetry.html.md +++ b/website/source/docs/agent/telemetry.html.md @@ -150,7 +150,7 @@ This is a full list of metrics emitted by Consul. counter - `consul.acl.blocked.<check|node|service>.registration` + `consul.acl.blocked..registration` This increments whenever a registration fails for an entity (check, node or service) is blocked by an ACL requests counter diff --git a/website/source/docs/agent/watches.html.md b/website/source/docs/agent/watches.html.md index 2cc02cfe6..6fd9795fa 100644 --- a/website/source/docs/agent/watches.html.md +++ b/website/source/docs/agent/watches.html.md @@ -165,7 +165,7 @@ Here is an example configuration: { "type": "keyprefix", "prefix": "foo/", - "args": ["/usr/bin/my-service-handler.sh", "-redis"] + "args": ["/usr/bin/my-prefix-handler.sh", "-redis"] } ``` @@ -384,7 +384,7 @@ events. These are fired using the [consul event](/docs/commands/event.html) comm It takes only a single optional "name" parameter which restricts the watch to only events with the given name. -This maps to the `v1/event/list` API internally. +This maps to the `/v1/event/list` API internally. Here is an example configuration: @@ -392,13 +392,13 @@ Here is an example configuration: { "type": "event", "name": "web-deploy", - "args": ["/usr/bin/my-service-handler.sh", "-web-deploy"] + "args": ["/usr/bin/my-event-handler.sh", "-web-deploy"] } ``` Or, using the watch command: - $ consul watch -type=event -name=web-deploy /usr/bin/my-deploy-handler.sh -web-deploy + $ consul watch -type=event -name=web-deploy /usr/bin/my-event-handler.sh -web-deploy An example of the output of this command: diff --git a/website/source/docs/connect/connect-internals.html.md b/website/source/docs/connect/connect-internals.html.md index 846f39476..ff2f4c03e 100644 --- a/website/source/docs/connect/connect-internals.html.md +++ b/website/source/docs/connect/connect-internals.html.md @@ -96,7 +96,7 @@ in multiple datacenters (such as the [geo failover](https://learn.hashicorp.com/ [Intentions](/docs/connect/intentions.html) verify connections between services by source and destination name seamlessly across datacenters. -Connections can be made via gateways to enable when communciating across +Connections can be made via gateways to enable when communicating across network topologies allowing connections between services in each datacenter without externally routable IPs at the service level. diff --git a/website/source/docs/connect/registration/service-registration.html.md b/website/source/docs/connect/registration/service-registration.html.md index b000bf360..279f1a8ba 100644 --- a/website/source/docs/connect/registration/service-registration.html.md +++ b/website/source/docs/connect/registration/service-registration.html.md @@ -210,7 +210,7 @@ registrations](/docs/agent/services.html#service-definition-parameter-case). } ``` -#### Direct to a Remote/Ingress in a Remote Dataceter +#### Direct to a Remote/Ingress in a Remote Datacenter ```json { "mode": "remote" diff --git a/website/source/docs/platform/k8s/index.html.md b/website/source/docs/platform/k8s/index.html.md index 942b8df4e..740e1d499 100644 --- a/website/source/docs/platform/k8s/index.html.md +++ b/website/source/docs/platform/k8s/index.html.md @@ -61,7 +61,7 @@ There are several ways to try Consul with Kubernetes in different environments. https://learn.hashicorp.com/consul/day-1-operations/kubernetes-reference?utm_source=consul.io&utm_medium=docs) guide provides recommended practices for production. - The [Consul and Kubernetes Deployment]( - https://learn.hashicorp.com/consul/day-1-operations/kubernetes-deployment-guide?utm_source=consul.io&utm_medium=docs) guide covers the necssary steps to install and configure a new Consul cluster on Kubernetes in production. + https://learn.hashicorp.com/consul/day-1-operations/kubernetes-deployment-guide?utm_source=consul.io&utm_medium=docs) guide covers the necessary steps to install and configure a new Consul cluster on Kubernetes in production. ## "consul-k8s" Project diff --git a/website/source/docs/platform/k8s/service-sync.html.md b/website/source/docs/platform/k8s/service-sync.html.md index 0f2ce91ac..b211b6eaf 100644 --- a/website/source/docs/platform/k8s/service-sync.html.md +++ b/website/source/docs/platform/k8s/service-sync.html.md @@ -255,7 +255,7 @@ metadata: ## Consul to Kubernetes This syncs Consul services into first-class Kubernetes services. -The sync service will creat an [`ExternalName`](https://kubernetes.io/docs/concepts/services-networking/service/#externalname) +The sync service will create an [`ExternalName`](https://kubernetes.io/docs/concepts/services-networking/service/#externalname) `Service` for each Consul service. The "external name" will be the Consul DNS name.