mirror of https://github.com/status-im/consul.git
website: document k8s go-discover (#4666)
This adds documentation for the `k8s` go-discover provider that will be part of 1.2.3.
This commit is contained in:
Mitchell Hashimoto
Matt Keeler
parent
220b17131f
commit
113f568509
|
|
@ -326,3 +326,40 @@ $ consul agent -retry-join "provider=packet auth_token=token project=uuid url=..
|
|||
- `auth_token` (required) - the authentication token for packet
|
||||
- `url` (optional) - a REST URL for packet
|
||||
- `address_type` (optional) - the type of address to check for in this provider ("private_v4", "public_v4" or "public_v6". Defaults to "private_v4")
|
||||
|
||||
|
||||
### Kubernetes (k8s)
|
||||
|
||||
The Kubernetes provider finds the IP addresses of pods with the matching
|
||||
[label or field selector](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/).
|
||||
This is useful for non-Kubernetes agents that are joining a server cluster
|
||||
running within Kubernetes.
|
||||
|
||||
The pod IP is used by default, which requires that the agent connecting can
|
||||
network to the pod IP. The `host_network` boolean can be set to true to use
|
||||
the host IP instead, but this requires the agent ports (Gossip, RPC, etc.)
|
||||
to be exported to the host as well.
|
||||
|
||||
By default, no port is specified. This causes Consul to use the default
|
||||
gossip port (default behavior with all join requests). The pod may specify
|
||||
the `consul.hashicorp.com/auto-join-port` annotation to set the port. The value
|
||||
may be an integer or a named port.
|
||||
|
||||
```sh
|
||||
$ consul agent -retry-join "provider=k8s label_selector=\"app=consul,component=server\""
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"retry-join": ["provider=k8s label_selector=..."]
|
||||
}
|
||||
```
|
||||
|
||||
- `provider` (required) - the name of the provider ("k8s" is the provider here)
|
||||
- `kubeconfig` (optional) - path to the kubeconfig file. If this isn't
|
||||
set, then in-cluster auth will be attempted. If that fails, the default
|
||||
kubeconfig paths are tried (`$HOME/.kube/config`).
|
||||
- `namespace` (optional) - the namespace to search for pods. If this isn't
|
||||
set, it defaults to all namespaces.
|
||||
- `label_selector` (optional) - the label selector for matching pods.
|
||||
- `field_selector` (optional) - the field selector for matching pods.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,50 @@
|
|||
---
|
||||
layout: "docs"
|
||||
page_title: "Out-of-Cluster Nodes - Kubernetes"
|
||||
sidebar_current: "docs-platform-k8s-ooc-nodes"
|
||||
description: |-
|
||||
Non-Kubernetes nodes can join a Consul cluster running within Kubernetes. These are considered "out-of-cluster" nodes.
|
||||
---
|
||||
|
||||
# Out-of-Cluster Nodes
|
||||
|
||||
Non-Kubernetes nodes can join a Consul cluster running within Kubernetes.
|
||||
These are considered "out-of-cluster" nodes.
|
||||
|
||||
## Auto-join
|
||||
|
||||
The recommended way to join a cluster running within Kubernetes is to
|
||||
use the ["k8s" cloud auto-join provider](/docs/agent/cloud-auto-join.html#kubernetes-k8s-).
|
||||
|
||||
The auto-join provider dynamically discovers IP addresses to join using
|
||||
the Kubernetes API. It authenticates with Kubernetes using a standard
|
||||
`kubeconfig` file. This works with all major hosted Kubernetes offerings
|
||||
as well as self-hosted installations.
|
||||
|
||||
The auto-join string below will join a Consul server cluster that is
|
||||
started using the [official Helm chart](/docs/platform/k8s/helm.html):
|
||||
|
||||
```sh
|
||||
$ consul agent -retry-join 'provider=k8s label_selector="app=consul,component=server"'
|
||||
```
|
||||
|
||||
By default, Consul will join the default Gossip port. Pods may set an
|
||||
annotation `consul.hashicorp.com/auto-join-port` to an integer value or
|
||||
a named port to specify the port for the auto-join to return. This enables
|
||||
different pods to have different exposed ports.
|
||||
|
||||
## Networking
|
||||
|
||||
Consul typically requires a fully connected network. Therefore, out-of-cluster
|
||||
nodes joining a cluster running within Kubernetes must be able to communicate
|
||||
to pod IPs or Kubernetes node IPs via the network.
|
||||
|
||||
-> **Consul Enterprise customers** may use
|
||||
[network segments](/docs/enterprise/network-segments/index.html) to
|
||||
enable non-fully-connected topologies. However, out-of-cluster nodes must still
|
||||
be able to communicate with the server pod or host IP addresses.
|
||||
|
||||
The auto-join provider discussed above will use pod IPs by default. The
|
||||
`host_network=true` setting may be set to use host IPs, however all the ports
|
||||
Consul requires must be exposed via a `hostPort`. If no ports are exposed via
|
||||
`hostPort`, the pod will not be discovered.
|
||||
|
|
@ -305,6 +305,9 @@
|
|||
<li<%= sidebar_current("docs-platform-k8s-helm") %>>
|
||||
<a href="/docs/platform/k8s/helm.html">Helm Chart</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-platform-k8s-ooc-nodes") %>>
|
||||
<a href="/docs/platform/k8s/out-of-cluster-nodes.html">Out-of-Cluster Nodes</a>
|
||||
</li>
|
||||
<li<%= sidebar_current("docs-platform-k8s-dns") %>>
|
||||
<a href="/docs/platform/k8s/dns.html">Consul DNS</a>
|
||||
</li>
|
||||
|
|
|
|||
Loading…
Reference in New Issue