docs/resources/etcd_cluster.md
# etcd cluster Resource
This resource allows to manage an etcd cluster on multiple hosts over SSH.
## Example Usage
```hcl
locals {
controller_ips = ["1.1.1.1"]
controller_names = ["controller01"]
}
resource "flexkube_pki" "pki" {
etcd {
peers = zipmap(local.controller_names, local.controller_ips)
servers = zipmap(local.controller_names, local.controller_ips)
}
}
resource "flexkube_etcd_cluster" "etcd" {
pki_yaml = flexkube_pki.pki.state_yaml
ssh {
user = "core"
password = "foo"
}
dynamic "member" {
for_each = flexkube_pki.pki.etcd[0].peers
content {
name = member.key
peer_address = member.value
server_address = member.value
host {
ssh {
address = member.value
}
}
}
}
}
```
## Argument Reference
* `member` - (Required) A `member` block as defined below. This block defines single etcd cluster member and can be specified multiple times.
* `image` - (Optional) Docker image with tag to be used to run etcd container. Defaults to `libflexkube` [default etcd image](https://github.com/flexkube/libflexkube/blob/master/pkg/defaults/defaults.go#L6).
* `ssh` - (Optional) A `ssh` block as defined below. This block defines global SSH settings shared by all members.
* `ca_certificate` - (Optional) If `pki_yaml` field is not set, this field must contain PEM encoded etcd X.509 CA certificate.
* `pki_yaml` - (Optional) This field can be set to `state_yaml` value of `flexkube_pki` resource to enable PKI integration for etcd, which allows automatic use of certificates generated by PKI resource.
---
A `member` block supports the following:
* `name` - (Required) Name of the member.
* `server_address` - (Required) IP address which should be used by the etcd member.
* `image` - (Optional) Docker image with tag to be used to run etcd container. Defaults to `libflexkube` [default etcd image](https://github.com/flexkube/libflexkube/blob/master/pkg/defaults/defaults.go#L6).
* `host` - (Optional) A `host` block as defined below. This block defines where to connect for creating the container.
* `ca_certificate` - (Optional) If top level `pki_yaml` field is not set, this field must contain PEM encoded etcd X.509 CA certificate. It will be used to verify incoming peer and client connections.
* `peer_certificate` - (Optional) If top level `pki_yaml` field is not set, this field must contain PEM encoded etcd X.509 peer certificate. It will be used for serving peer communication and as client certificate when talking to remote peers.
* `peer_key` - (Optional) If top level `pki_yaml` field is not set, this field must contain PEM encoded etcd X.509 peer certificate key.
* `initial_cluster` - (Optional) Value for `initial-cluster` etcd flag. If empty, it will be generated automatically and include all defined members.
* `peer_cert_allowed_cn` - (Optional) List of allowed CNs in X.509 client certificate for peer communication. This field is useful, when you have single peer certificate for all members and to distinguish then between the peers and the clients.
* `server_certificate` - (Optional) If top level `pki_yaml` field is not set, this field must contain PEM encoded etcd X.509 server certificate. It will be used for serving client communication.
* `server_key` - (Optional) If top level `pki_yaml` field is not set, this field must contain PEM encoded etcd X.509 server certificate key.
---
A `host` block supports the following:
* `direct` - (Optional) A `direct` block as defined below. Mutually exclusive with all other fields in this block. If defined, container will be created on local machine.
* `ssh` - (Optional) A `ssh` block as defined below. Mutually exclusive with all other fields in this block. If defined, container will be created on a remote machine using SSH connection.
---
A `direct` block does not support any arguments.
---
A `ssh` block supports the following:
* `address` - (Required) An address where SSH client should connect to. Can be either hostname of IP address.
* `port` - (Optional) Port where to open SSH connection. Defaults to `22`.
* `user` - (Optional) Username to use when opening SSH connection. Defaults to `root`.
* `password` - (Optional) Password to use for SSH authentication. Can be combined with `private_key` and SSH agent authentication methods.
* `connection_timeout` - (Optional) Duration for how long to wait before connection attempts times out, expressed in [Go Duration format](https://golang.org/pkg/time/#ParseDuration). Defaults to `30s`.
* `retry_timeout` - (Optional) Duration for how long to wait before giving up on connection attempts, expressed in [Go Duration format](https://golang.org/pkg/time/#ParseDuration). Defaults to `60s`.
* `retry_interval` - (Optional) Duration for how long to wait between connection attempts, expressed in [Go Duration format](https://golang.org/pkg/time/#ParseDuration). Defaults to `1s`.
* `private_key` - (Optional) PEM encoded privat key to be used for authentication. Can be combined with `password` and SSH agent authentication methods.
---
A `mount` block supports the following:
* `source` - (Required) A host directory to be mounted in the container.
* `target` - (Required) Path in the container where host directory should be mounted.
* `propagation` - (Optional) Propagation mode to be set on the mount. See [Docker](https://docs.docker.com/storage/bind-mounts/#configure-bind-propagation) documentation for allowed values.
## Attribute Reference
* `state` - A list of `host_configured_container` blocks as defined below. This attribute represents generated configuration of the managed containers. Sensitive values like configuration files content, environment variables or SSH password are replaced with SHA256 of the values. To get the actual value, use `state_sensitive` block.
* `state_sensitive` - A list of `host_configured_container` blocks as defined below. This attribute represents generated configuration of the managed containers. This attribute is marked entirely as sensitive, so it won't show up detailed in a plan. To see specific changes in generated configuration, use `state` attribute.
* `state_yaml` - State of created containers in YAML format. Can be dumped to a `state.yaml` file and used together with `flexkube kubelet-pool` command.
* `config_yaml` - Generated configuration in YAML format, which can be used by the `flexkube kubelet-pool` command.
---
A `host_configured_container` block supports the following:
* `name` - Name of the container.
* `container` - A `container` block as defined below. Contains container configuration parameters.
* `config_files` - A map of configuration files which are created for the container on the host. The key is the path on the host to the configuration file and the value is either a configuration file content or it's SHA256, depending if read from `state` or from `state_sensitive` attribute.
* `host` - A `host` block as defined above. Describes on which host the container is created.
---
A `container` block supports the following:
* `config` - A `config` block as defined below. Contains container configuration attributes.
* `runtime` - A `runtime` block as defined below. Includes container runtime configuration.
* `status` - A `status` block as defined below. Contains container status information.
---
A `config` block supports the following:
* `name` - Name of the managed container.
* `image` - Container image used.
* `privileged` - If `true`, the container runs as a privileged process on the host.
* `args` - Arguments used for a container.
* `entrypoint` - Binary name which runs in the container.
* `port` - A `port` block as defined below. Contains ports, which are exposed by the container.
* `mount` - A list of `mount` blocks as defined above. Contains information which host paths are mounted into the container.
* `network_mode` - Defines what network mode container use. Actual value may depend on used container runtime.
* `pid_mode` - Defines in which PID mode container runs. Actual value may depend on used container runtime.
* `ipc_mode` - Defines in which IPC mode container runs. Actual value may depend on used container runtime.
* `user` - Name of the user or UID used by the container.
* `group` - Name of the group or GID used by the container.
---
A `port` block supports the following:
* `ip` - IP on which the port is exposed.
* `port` - Exposed port number.
* `protocol` - Exposed protocol.
---
A `runtime` block supports the following:
* `docker` - A `docker` block as defined below. Container Docker runtime configuration attributes.
---
A `docker` block supports the following:
* `host` - URL used to talk to Docker runtime. Defaults to `unix:///var/run/docker.sock`.
---
A `status` block supports the following:
* `id` - ID of the created container given by used container runtime.
* `status` - Text status of the container. If field is empty, it means that the container does not exist.