Skip to content

README.md

Latest commit

 

History

History
166 lines (128 loc) · 5.68 KB

README.md

File metadata and controls

166 lines (128 loc) · 5.68 KB

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.