94 lines
6.4 KiB
Markdown
94 lines
6.4 KiB
Markdown
# Containerized CoreDNS on Container Optimized OS
|
|
|
|
This module manages a `cloud-config` configuration that starts a containerized [CoreDNS](https://coredns.io/) service on Container Optimized OS, using the [official image](https://hub.docker.com/r/coredns/coredns/).
|
|
|
|
The resulting `cloud-config` can be customized in a number of ways:
|
|
|
|
- a custom CoreDNS configuration can be set using the `coredns_config` variable
|
|
- additional files (eg for hosts or zone files) can be passed in via the `files` variable
|
|
- a completely custom `cloud-config` can be passed in via the `cloud_config` variable, and additional template variables can be passed in via `config_variables`
|
|
|
|
The default instance configuration inserts iptables rules to allow traffic on the DNS TCP and UDP ports, and the 8080 port for the optional HTTP health check that can be enabled via the CoreDNS [health plugin](https://coredns.io/plugins/health/).
|
|
|
|
Logging and monitoring are enabled via the [Google Cloud Logging driver](https://docs.docker.com/config/containers/logging/gcplogs/) configured for the CoreDNS container, and the [Node Problem Detector](https://cloud.google.com/container-optimized-os/docs/how-to/monitoring) service is started by default on boot.
|
|
|
|
The module renders the generated cloud config in the `cloud_config` output, to be used in instances or instance templates via the `user-data` metadata.
|
|
|
|
For convenience during development or for simple use cases, the module can optionally manage a single instance via the `test_instance` variable. If the instance is not needed the `instance*tf` files can be safely removed. Refer to the [top-level README](../README.md) for more details on the included instance.
|
|
|
|
## Examples
|
|
|
|
### Default CoreDNS configuration
|
|
|
|
This example will create a `cloud-config` that uses the module's defaults, creating a simple DNS forwarder.
|
|
|
|
```hcl
|
|
module "cos-coredns" {
|
|
source = "./modules/cloud-config-container/coredns"
|
|
}
|
|
|
|
# use it as metadata in a compute instance or template
|
|
resource "google_compute_instance" "default" {
|
|
metadata = {
|
|
user-data = module.cos-coredns.cloud_config
|
|
}
|
|
```
|
|
|
|
### Custom CoreDNS configuration
|
|
|
|
This example will create a `cloud-config` using a custom CoreDNS configuration, that leverages the [CoreDNS hosts plugin]() to serve a single zone via an included `hosts` format file.
|
|
|
|
```hcl
|
|
module "cos-coredns" {
|
|
source = "./modules/cloud-config-container/coredns"
|
|
coredns_config = "./modules/cloud-config-container/coredns/Corefile-hosts"
|
|
files = {
|
|
"/etc/coredns/example.hosts" = {
|
|
content = "127.0.0.2 foo.example.org foo"
|
|
owner = null
|
|
permissions = "0644"
|
|
}
|
|
}
|
|
```
|
|
|
|
### CoreDNS instance
|
|
|
|
This example shows how to create the single instance optionally managed by the module, providing all required attributes in the `test_instance` variable. The instance is purposefully kept simple and should only be used in development, or when designing infrastructures.
|
|
|
|
```hcl
|
|
module "cos-coredns" {
|
|
source = "./modules/cloud-config-container/coredns"
|
|
test_instance = {
|
|
project_id = "my-project"
|
|
zone = "europe-west1-b"
|
|
name = "cos-coredns"
|
|
type = "f1-micro"
|
|
network = "default"
|
|
subnetwork = "https://www.googleapis.com/compute/v1/projects/my-project/regions/europe-west1/subnetworks/my-subnet"
|
|
}
|
|
}
|
|
```
|
|
<!-- BEGIN TFDOC -->
|
|
|
|
## Variables
|
|
|
|
| name | description | type | required | default |
|
|
|---|---|:---:|:---:|:---:|
|
|
| [cloud_config](variables.tf#L17) | Cloud config template path. If null default will be used. | <code>string</code> | | <code>null</code> |
|
|
| [config_variables](variables.tf#L23) | Additional variables used to render the cloud-config and CoreDNS templates. | <code>map(any)</code> | | <code>{}</code> |
|
|
| [coredns_config](variables.tf#L29) | CoreDNS configuration path, if null default will be used. | <code>string</code> | | <code>null</code> |
|
|
| [docker_logging](variables.tf#L35) | Log via the Docker gcplogs driver. Disable if you use the legacy Logging Agent instead. | <code>bool</code> | | <code>true</code> |
|
|
| [file_defaults](variables.tf#L41) | Default owner and permissions for files. | <code title="object({ owner = string permissions = string })">object({…})</code> | | <code title="{ owner = "root" permissions = "0644" }">{…}</code> |
|
|
| [files](variables.tf#L53) | Map of extra files to create on the instance, path as key. Owner and permissions will use defaults if null. | <code title="map(object({ content = string owner = string permissions = string }))">map(object({…}))</code> | | <code>{}</code> |
|
|
| [test_instance](variables-instance.tf#L17) | Test/development instance attributes, leave null to skip creation. | <code title="object({ project_id = string zone = string name = string type = string network = string subnetwork = string })">object({…})</code> | | <code>null</code> |
|
|
| [test_instance_defaults](variables-instance.tf#L30) | Test/development instance defaults used for optional configuration. If image is null, COS stable will be used. | <code title="object({ disks = map(object({ read_only = bool size = number })) image = string metadata = map(string) nat = bool service_account_roles = list(string) tags = list(string) })">object({…})</code> | | <code title="{ disks = {} image = null metadata = {} nat = false service_account_roles = [ "roles/logging.logWriter", "roles/monitoring.metricWriter" ] tags = ["ssh"] }">{…}</code> |
|
|
|
|
## Outputs
|
|
|
|
| name | description | sensitive |
|
|
|---|---|:---:|
|
|
| [cloud_config](outputs.tf#L17) | Rendered cloud-config file to be passed as user-data instance metadata. | |
|
|
| [test_instance](outputs-instance.tf#L17) | Optional test instance name and address. | |
|
|
|
|
<!-- END TFDOC -->
|