docs/resources/controlplane.md
# Controlplane Resource
This resource allows to manage static Kubernetes controlplane containers.
## Example Usage
```hcl
locals {
controller_ips = ["1.1.1.1"]
controller_names = ["controller01"]
first_controller_ip = local.controller_ips[0]
api_port = 6443
bootstrap_api_bind = "0.0.0.0"
}
resource "flexkube_pki" "pki" {
etcd {
client_cns = [
"root",
"kube-apiserver",
"prometheus",
]
}
kubernetes {
kube_api_server {
external_names = ["kube-apiserver.example.com"]
server_ips = concat(local.controller_ips, ["127.0.1.1", "11.0.0.1"])
}
}
}
resource "flexkube_controlplane" "bootstrap" {
pki_yaml = flexkube_pki.pki.state_yaml
kube_apiserver {
service_cidr = "11.0.0.0/24"
etcd_servers = formatlist("https://%s:2379", local.controller_ips)
bind_address = local.bootstrap_api_bind
advertise_address = local.first_controller_ip
secure_port = local.api_port
}
kube_controller_manager {
flex_volume_plugin_dir = "/var/lib/kubelet/volumeplugins"
}
api_server_address = local.first_controller_ip
api_server_port = local.api_port
ssh {
address = "127.0.0.1"
port = 12345
password = "bar"
connection_timeout = "1s"
retry_interval = "1s"
retry_timeout = "1s"
}
}
```
## Argument Reference
* `api_server_address` - (Optional) If specified, defines on which address kube-apiserver process should bind and where kube-scheduler and kube-controller-manager should connect to the Kubernetes API.
* `api_server_port` - (Optional) If specified, defines on which port kube-apiserver process should bind and where kube-scheduler and kube-controller-manager should connect to the Kubernetes API.
* `pki_yaml` - (Optional) This field can be set to `state_yaml` value of `flexkube_pki` resource to enable PKI integration for kubelet, which allows automatic use of certificates generated by PKI resource.
* `ssh` - (Optional) A `ssh` block as defined below. This block defines global SSH settings shared by all instances.
* `common` - (Optional) A `common` block as defined below. This block allows setting fields for all 3 controlplane components.
* `kube_apiserver` - (Optional) A `kube_apiserver` block as defined below. Contains `kube-apiserver` specific settings.
* `kube_scheduler` - (Optional) A `kube_scheduler` block as defined below. Contains `kube-scheduler` specific settings.
* `kube_controller_manager` - (Optional) A `kube_controller_manager` block as defined below. Contains `kube-controller-manager` specific settings.
---
A `common` block supports the following:
* `kubernetes_ca_certificate` - (Optional) A PEM encoded Kubernetes X.509 CA certificate.
* `front_proxy_ca_certificate` - (Optional) A PEM encoded Kubernetes Front Proxy X.509 CA certificate.
---
A `kube_apiserver` block supports the following:
* `common` - (Optional) A `common` block as defined above. This block overrides settings set in global `common` block.
* `host` - (Optional) A `host` block as defined below. This block defines where to connect for creating the container.
* `api_server_certificate` - (Optional) PEM encoded X.509 server certificate user to serve API requests. Optional if `pki_yaml` top field is set.
* `api_server_key` - (Optional) PEM encoded X.509 certificate key for `api_server_certificate`. Optional if `pki_yaml` top field is set.
* `front_proxy_certificate` - (Optional) PEM encoded X.509 client certificate used to send requests to extension API servers. Optional if `pki_yaml` top field is set.
* `front_proxy_key` - (Optional) PEM encoded X.509 certificate key for `front_proxy_certificate`. Optional if `pki_yaml` top field is set.
* `kubelet_client_certificate` - (Optional) PEM encoded X.509 client certificate used to send requests to kubelets. Optional if `pki_yaml` top field is set.
* `kubelet_client_key` - (Optional) PEM encoded X.509 certificate key for `kubelet_client_certificate`. Optional if `pki_yaml` top field is set.
* `service_account_private_key` - (Optional) PEM encoded RSA private key used to verify service account tokens. Optional if `pki_yaml` top field is set.
* `etcd_ca_certificate` - (Optional) PEM encoded X.509 CA certificate used to verify authority of etcd servers. Optional if `pki_yaml` top field is set.
* `etcd_client_certificate` - (Optional) PEM encode X.509 client certificate used to send requests to etcd servers. Optional if `pki_yaml` top field is set.
* `etcd_client_key` - (Optional) PEM encoded X.509 certificate key for `etcd_client_certificate`. Optional if `pki_yaml` top field is set.
* `service_cidr` - (Optional) Service CIDR for cluster.
* `etcd_servers` - (Optional) List of etcd servers to use. Example value: `["https://10.0.0.2:2379"]`.
* `bind_address` - (Optional) IP address to bind.
* `advertise_address` - (Optional) Address to advertise to the cluster, where kubernetes.default.svc.cluster.local service will be pointing to.
* `secure_port` - (Optional) Port to bind.
---
A `kube_scheduler` block supports the following:
* `common` - (Optional) A `common` block as defined above. This block overrides settings set in global `common` block.
* `host` - (Optional) A `host` block as defined below. This block defines where to connect for creating the container.
* `kubeconfig - (Optional) A `kubeconfig` block as defined below. This block defines how `kube-scheduler` connects to Kubernetes API. Optional if `pki_yaml`, `api_server_address` and `api_server_port` fields are set.
---
A `kube_controller_manager` block supports the following:
* `flex_volume_plugin_dir` - (Required) Path to flex volumes plugin directory. Usually `/var/lib/kubelet/volumeplugins`.
* `common` - (Optional) A `common` block as defined above. This block overrides settings set in global `common` block.
* `host` - (Optional) A `host` block as defined below. This block defines where to connect for creating the container.
* `kubeconfig - (Optional) A `kubeconfig` block as defined below. This block defines how `kube-scheduler` connects to Kubernetes API. Optional if `pki_yaml`, `api_server_address` and `api_server_port` fields are set.
* `kubernetes_ca_key` - (Optional) PEM encoded Kubernetes CA X.509 certificate key, which will be used to sign requested certificates via Kubernetes API. Optional if `pki_yaml` top field is set.
* `service_account_private_key` - (Optional) PEM encoded Kubernetes service account RSA private key, which will be used to sign service account tokens. Optional if `pki_yaml` top field is set.
* `root_ca_certificate` - (Optional) PEM encoded Root CA X.509 certificate, which will be bundled with service account token. This is needed for clients, which do more than 1 level depth verification of TLS certificates, like `curl`. Optional if `pki_yaml` top field is set.
---
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.
## 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.