Terraform DigitalOcean Kubernetes Cluster (DOKS) Module

This Terraform module provides a simple and flexible way to create and manage Kubernetes clusters on DigitalOcean (DOKS).

Description

The terraform-do-doks module abstracts the complexity of creating a Kubernetes cluster on DigitalOcean, allowing you to define your infrastructure declaratively. It includes features such as:

• DOKS Cluster: Create a fully managed Kubernetes cluster
• Multiple Node Pools: Define multiple node groups with different configurations
• Autoscaling: Configure automatic node scaling
• Integrations: Enable container registry and routing
• Taints and Labels: Control which pods can run on which nodes
• Project Integration: Automatically assign resources to DigitalOcean projects

Requirements

• Terraform >= 1.0
• DigitalOcean Provider >= 2.0
• DigitalOcean API token configured in your environment

Key Features

Base Cluster

• Configurable name, region, and Kubernetes version
• Custom VPC for the cluster
• Tags to organize your resources

Node Pools

• Default Pool: Included automatically
• Additional Pools: Define as many node groups as you need
• Autoscaling: Each additional pool has autoscaling enabled
• Taints and Labels: For advanced pod scheduling control

Integration and Features

• Container Registry: Optional integration with DigitalOcean Container Registry
• Routing Agent: Ingress controller for DigitalOcean
• Cluster Autoscaler: Configurable for automatic node scaling

Variables

Required Variables

Variable	Type	Description
doks_name	string	DOKS cluster name
region	string	DigitalOcean region (e.g., "nyc3", "sfo3")
doks_version	string	Kubernetes version (e.g., "1.27.3-do.0")
vpc_id	string	VPC ID where the cluster will be created
subnets	object	Cluster and service subnets

Optional Variables

Variable	Type	Description	Default Value
tags	list(string)	Tags applied to the cluster	[]
project_id	string	DigitalOcean project ID	null
integrations	object	Cluster integrations	See table below
cluster_autoscaler_configuration	object	Autoscaling configuration	{}
default_pool	object	Default node pool configuration	See table below
pools	map(object)	Additional node pools	{}

Integrations (integrations)

{
  registry = bool          # Enable Container Registry (default: true)
  routing_agent = bool    # Enable ingress controller (default: false)
}

Default Pool (default_pool)

{
  size = string                        # Machine size (default: "s-1vcpu-1gb")
  node_count = number                  # Number of nodes (default: 1)
  tags = optional(list(string))       # Tags for the nodes
  labels = optional(map(string))      # Kubernetes labels
  taints = optional(list(object({
    key = string
    value = string
    effect = string                    # "NoSchedule", "PreferNoSchedule", "NoExecute"
  })))
}

Additional Pools (pools)

{
  "pool-name" = {
    size = string                           # Machine size (required)
    min_nodes = number                      # Minimum nodes (required)
    max_nodes = number                      # Maximum nodes (required)
    tags = optional(list(string))          # Tags for the nodes
    labels = optional(map(string))         # Kubernetes labels
    taints = optional(list(object({
      key = string
      value = string
      effect = string
    })))
  }
}

Outputs

Output	Description
cluster_id	DOKS cluster ID
cluster_endpoint	Cluster API endpoint (sensitive)
kube_config	Complete kubeconfig configuration (sensitive)
node_pool_ids	IDs of all node pools

Basic Usage Example

See the examples/basic folder for a simple example of how to use this module.

Advanced Usage Example

See the examples/advanced folder for a complete example with multiple pools, autoscaling, and advanced configurations.

Important Notes

1. Subnets: The module requires you to specify subnets (subnets.cluster and subnets.services). These must not overlap with your VPC CIDR range.

2. Default Pool Autoscaling: The default pool does not have autoscaling enabled automatically. Use additional pools if you need autoscaling.

3. Kubernetes Version: Check the DigitalOcean documentation for available versions in your region.

4. Taints and Tolerations: If you define taints, ensure your pods have the corresponding tolerations.

Module Structure

terraform-do-doks/
├── main.tf                 # Main resources (cluster and pools)
├── variables.tf            # Variable definitions
├── outputs.tf              # Module outputs
├── versions.tf             # Version requirements
├── README.md              # This file
└── examples/
    ├── basic/             # Basic example
    │   ├── main.tf
    │   └── terraform.tfvars
    └── advanced/          # Advanced example
        ├── main.tf
        └── terraform.tfvars

Troubleshooting

Cluster is not created correctly

• Verify that you have a valid DigitalOcean API token
• Check that the region exists and is available
• Ensure the VPC exists and the ID is correct

Nodes are not assigned to pools correctly

• Verify that you have specified taints correctly in the pods
• Check that labels match in the pod selectors

License

This module is available under the MIT license.

Support

To report issues or suggestions, see the project repository.