{"id":22271586,"url":"https://github.com/appthrust/capt","last_synced_at":"2025-07-03T03:06:08.692Z","repository":{"id":262925655,"uuid":"884579475","full_name":"appthrust/capt","owner":"appthrust","description":"CAPT (Cluster API Provider Terraform) - A Kubernetes-native solution for managing EKS clusters using Terraform and Crossplane. Enables modular infrastructure management with workspace templates, ClusterClass support, and secure configuration handling.","archived":false,"fork":false,"pushed_at":"2025-02-16T23:37:08.000Z","size":901,"stargazers_count":5,"open_issues_count":2,"forks_count":0,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-06-26T10:56:41.794Z","etag":null,"topics":["cluster-api","kubernetes","terraform"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/appthrust.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":".github/SUPPORT.md","governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-11-07T02:21:15.000Z","updated_at":"2025-03-06T01:45:55.000Z","dependencies_parsed_at":"2024-11-15T04:17:36.331Z","dependency_job_id":"c03ccd69-c8ff-45f0-8f19-d37ca5b9ff6e","html_url":"https://github.com/appthrust/capt","commit_stats":null,"previous_names":["appthrust/capt"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/appthrust/capt","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appthrust%2Fcapt","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appthrust%2Fcapt/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appthrust%2Fcapt/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appthrust%2Fcapt/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/appthrust","download_url":"https://codeload.github.com/appthrust/capt/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/appthrust%2Fcapt/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263250601,"owners_count":23437288,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cluster-api","kubernetes","terraform"],"created_at":"2024-12-03T12:12:38.373Z","updated_at":"2025-07-03T03:06:08.673Z","avatar_url":"https://github.com/appthrust.png","language":"Go","readme":"# CAPT (Cluster API Provider Terraform)\n\nCAPT is a Cluster API provider that leverages Terraform to create and manage EKS clusters on AWS. It uses Crossplane's Terraform Provider to manage infrastructure components through Kubernetes-native resources.\n\n## Overview\n\nCAPT implements a modular approach to EKS cluster management where each infrastructure component (VPC, Control Plane, Machine Resources) is managed through its own WorkspaceTemplate. This design enables:\n\n- Clear separation of concerns between infrastructure components\n- Reusable infrastructure templates\n- Secure configuration management through Kubernetes secrets\n- Terraform-based state management and drift detection\n- ClusterClass support for standardized cluster deployments\n- Independent compute resource management through Machine concept\n\n## Architecture\n\nThe cluster creation is divided into four main components:\n\n1. VPC Infrastructure\n2. EKS Control Plane\n3. Compute Resources (Machine)\n4. Cluster Configuration\n\n### Core Resource Relationships\n\n```mermaid\ngraph TD\n    subgraph \"Cluster API Core\"\n        Cluster\n    end\n\n    subgraph \"CAPT Resources\"\n        CAPTCluster\n        CAPTControlPlane\n    end\n\n    subgraph \"Infrastructure Templates\"\n        VPCTemplate[WorkspaceTemplate\u003cbr/\u003eVPC]\n        CPTemplate[WorkspaceTemplate\u003cbr/\u003eControlPlane]\n    end\n\n    subgraph \"Infrastructure Deployment\"\n        VPCApply[WorkspaceTemplateApply\u003cbr/\u003eVPC]\n        CPApply[WorkspaceTemplateApply\u003cbr/\u003eControlPlane]\n    end\n\n    subgraph \"Terraform Resources\"\n        VPCWorkspace[Workspace\u003cbr/\u003eVPC]\n        CPWorkspace[Workspace\u003cbr/\u003eControlPlane]\n    end\n\n    Cluster --\u003e CAPTCluster\n    Cluster --\u003e CAPTControlPlane\n\n    CAPTCluster --\u003e |references| VPCTemplate\n    CAPTControlPlane --\u003e |references| CPTemplate\n\n    CAPTCluster --\u003e |creates| VPCApply\n    CAPTControlPlane --\u003e |creates| CPApply\n\n    VPCApply --\u003e |references| VPCTemplate\n    CPApply --\u003e |references| CPTemplate\n\n    VPCApply --\u003e |creates| VPCWorkspace\n    CPApply --\u003e |creates| CPWorkspace\n\n    CPApply -.-\u003e |depends on| VPCApply\n```\n\n### Component Lifecycle Flow\n\n```mermaid\nsequenceDiagram\n    participant C as Cluster\n    participant CC as CAPTCluster\n    participant CP as CAPTControlPlane\n    participant VT as VPC Template\n    participant VA as VPC Apply\n    participant CT as ControlPlane Template\n    participant CA as ControlPlane Apply\n\n    C-\u003e\u003eCC: Create\n    CC-\u003e\u003eVT: Reference\n    CC-\u003e\u003eVA: Create\n    VA-\u003e\u003eVT: Use Template\n    VA-\u003e\u003eVA: Apply Infrastructure\n\n    C-\u003e\u003eCP: Create\n    CP-\u003e\u003eCT: Reference\n    CP-\u003e\u003eCA: Create\n    CA-\u003e\u003eCT: Use Template\n    CA--\u003e\u003eVA: Wait for VPC\n    CA-\u003e\u003eCA: Apply Infrastructure\n```\n\nEach component is managed independently through WorkspaceTemplates and can be templated using ClusterClass. The controllers automatically manage WorkspaceTemplateApply resources for infrastructure provisioning.\n\n## Key Benefits\n\n### 1. Declarative Infrastructure Management\n- Version control and tagging for clear configuration management\n- State tracking for configuration drift detection\n- Utilization of standard Terraform modules\n- ClusterClass templates for standardized deployments\n- Automatic WorkspaceTemplateApply management by controllers\n- VPC retention capability for shared infrastructure scenarios\n\n### 2. Robust Dependency Management\n- Explicit dependency definition between components (e.g., VPC and EKS)\n- Secure configuration propagation through secrets\n- Independent lifecycle management for each component\n- Template-based configuration with variable substitution\n\n### 3. Secure Configuration Management\n- Secure handling of sensitive information through Kubernetes secrets\n- Automatic OIDC authentication and IAM role configuration\n- Centralized security group and network policy management\n- Secure configuration migration between environments\n\n### 4. High Operability and Reusability\n- Reusable infrastructure templates\n- Customization through environment-specific variables and tags\n- Automatic management of Helm charts and EKS addons\n- Compatibility with existing Terraform modules\n- ClusterClass for consistent cluster deployments\n\n### 5. Modern Kubernetes Feature Integration\n- Automatic Fargate profile configuration\n- Efficient node scaling with Karpenter\n- Integrated EKS addon management\n- Extensibility through Custom Resource Definitions (CRDs)\n- ClusterTopology support for advanced cluster management\n\n## Installation\n\n### Using Helm Chart\n\nCAPT controller can be installed using Helm Chart:\n\n```bash\nhelm install capt oci://ghcr.io/appthrust/charts/capt --version 0.2.1\n```\n\nThe installation will deploy the following components:\n- CAPT controller\n- Custom Resource Definitions (CRDs)\n- RBAC configurations\n\nNote: Cluster API must be installed in your cluster before installing CAPT. For detailed installation instructions, please refer to [INSTALL.md](INSTALL.md).\n\n### Using clusterctl\n\nCAPT is compatible with clusterctl and follows the clusterctl provider contract. CAPT functions as both an Infrastructure Provider and Control Plane Provider.\n\n#### Configuration\n\nAdd CAPT to your clusterctl configuration (`~/.cluster-api/clusterctl.yaml`):\n\n```yaml\nproviders:\n  - name: \"capt\"\n    url: \"https://github.com/appthrust/capt/releases/latest/infrastructure-components.yaml\"\n    type: \"InfrastructureProvider\"\n  - name: \"capt\"\n    url: \"https://github.com/appthrust/capt/releases/latest/control-plane-components.yaml\"\n    type: \"ControlPlaneProvider\"\n```\n\n#### Installation\n\n```bash\n# Add CAPT as both Infrastructure and Control Plane provider\nclusterctl init --core cluster-api --infrastructure capt --control-plane capt\n```\n\n#### Creating Clusters\n\n```bash\n# Set environment variables\nexport AWS_REGION=ap-northeast-1\nexport CLUSTER_NAME=my-cluster\nexport KUBERNETES_VERSION=1.33.2\n\n# Generate cluster manifest\nclusterctl generate cluster $CLUSTER_NAME \\\n  --infrastructure capt \\\n  --kubernetes-version $KUBERNETES_VERSION \\\n  --target-namespace default \u003e cluster.yaml\n\n# Apply the cluster\nkubectl apply -f cluster.yaml\n```\n\nFor detailed clusterctl integration guide, see [docs/clusterctl-integration.md](docs/clusterctl-integration.md).\n\n## Quick Start Guide\n\nThis guide will help you get started with using CAPT to manage your EKS clusters.\n\n### Prerequisites\n\nBefore you begin, ensure you have:\n\n1. CAPT installed (see [INSTALL.md](INSTALL.md))\n2. AWS credentials properly configured\n3. A running Kubernetes cluster with Cluster API and CAPT\n\n### Creating Your First EKS Cluster\n\n1. Create a VPC WorkspaceTemplate:\n   ```yaml\n   apiVersion: infrastructure.cluster.x-k8s.io/v1beta1\n   kind: WorkspaceTemplate\n   metadata:\n     name: simple-vpc\n   spec:\n     template:\n       metadata:\n         description: \"Simple VPC configuration\"\n       spec:\n         module:\n           source: \"terraform-aws-modules/vpc/aws\"\n           version: \"5.0.0\"\n         variables:\n           name:\n             value: \"simple-vpc\"\n           cidr:\n             value: \"10.0.0.0/16\"\n   ```\n   Save this as `simple-vpc.yaml` and apply it:\n   ```bash\n   kubectl apply -f simple-vpc.yaml\n   ```\n\n2. Create a CAPTCluster resource:\n   ```yaml\n   apiVersion: infrastructure.cluster.x-k8s.io/v1beta1\n   kind: CAPTCluster\n   metadata:\n     name: simple-cluster\n   spec:\n     region: us-west-2\n     vpcTemplateRef:\n       name: simple-vpc\n   ```\n   Save this as `simple-cluster.yaml` and apply it:\n   ```bash\n   kubectl apply -f simple-cluster.yaml\n   ```\n\n3. Create a Cluster resource:\n   ```yaml\n   apiVersion: cluster.x-k8s.io/v1beta1\n   kind: Cluster\n   metadata:\n     name: simple-cluster\n   spec:\n     infrastructureRef:\n       apiVersion: infrastructure.cluster.x-k8s.io/v1beta1\n       kind: CAPTCluster\n       name: simple-cluster\n   ```\n   Save this as `cluster.yaml` and apply it:\n   ```bash\n   kubectl apply -f cluster.yaml\n   ```\n\n### Monitoring Cluster Creation\n\n1. Check the status of your cluster:\n   ```bash\n   kubectl get clusters\n   ```\n\n2. View the CAPTCluster resource:\n   ```bash\n   kubectl get captclusters\n   ```\n\n3. Check the WorkspaceTemplateApply resources:\n   ```bash\n   kubectl get workspacetemplateapplies\n   ```\n\n### Accessing Your EKS Cluster\n\nOnce the cluster is ready:\n\n1. Get the kubeconfig for your new EKS cluster:\n   ```bash\n   aws eks get-token --cluster-name simple-cluster \u003e kubeconfig\n   ```\n\n2. Use the new kubeconfig to interact with your EKS cluster:\n   ```bash\n   kubectl --kubeconfig=./kubeconfig get nodes\n   ```\n\n## Usage\n\n### 1. Using ClusterClass (Recommended)\n\nClusterClass provides a templated approach to cluster creation, enabling standardized deployments across your organization:\n\n1. Define ClusterClass:\n```yaml\napiVersion: cluster.x-k8s.io/v1beta1\nkind: ClusterClass\nmetadata:\n  name: eks-class\nspec:\n  controlPlane:\n    ref:\n      apiVersion: controlplane.cluster.x-k8s.io/v1beta1\n      kind: CaptControlPlaneTemplate\n      name: eks-control-plane-template\n  variables:\n    - name: controlPlane.version\n      required: true\n      schema:\n        openAPIV3Schema:\n          type: string\n          enum: [\"1.27\", \"1.28\", \"1.29\", \"1.30\", \"1.31\", \"1.32\", \"1.33\"]\n```\n\n2. Create Cluster using ClusterClass:\n```yaml\napiVersion: cluster.x-k8s.io/v1beta1\nkind: Cluster\nmetadata:\n  name: demo-cluster\nspec:\n  topology:\n    class: eks-class\n    version: \"1.33\"\n    variables:\n      - name: controlPlane.version\n        value: \"1.33\"\n      - name: environment\n        value: dev\n```\n\n### 2. Traditional Approach\n\n#### Create VPC Infrastructure Template with Retention\n\n```yaml\napiVersion: infrastructure.cluster.x-k8s.io/v1beta1\nkind: WorkspaceTemplate\nmetadata:\n  name: vpc-template\nspec:\n  template:\n    metadata:\n      description: \"Standard VPC configuration\"\n    spec:\n      module:\n        source: \"terraform-aws-modules/vpc/aws\"\n        version: \"5.0.0\"\n      variables:\n        name:\n          value: \"${var.name}\"\n        cidr:\n          value: \"10.0.0.0/16\"\n```\n\n#### Create CAPTCluster with VPC Retention\n\n```yaml\napiVersion: infrastructure.cluster.x-k8s.io/v1beta1\nkind: CAPTCluster\nmetadata:\n  name: demo-cluster\nspec:\n  region: us-west-2\n  vpcTemplateRef:\n    name: vpc-template\n    namespace: default\n  retainVpcOnDelete: true  # VPC will be retained when cluster is deleted\n```\n\n#### Create Compute Resources (Machine)\n\n```yaml\napiVersion: infrastructure.cluster.x-k8s.io/v1beta1\nkind: CAPTMachineDeployment\nmetadata:\n  name: demo-nodegroup\nspec:\n  replicas: 3\n  template:\n    spec:\n      workspaceTemplateRef:\n        name: nodegroup-template\n      instanceType: t3.medium\n      diskSize: 50\n```\n\n#### Create NodeGroup Template\n\n```yaml\napiVersion: infrastructure.cluster.x-k8s.io/v1beta1\nkind: WorkspaceTemplate\nmetadata:\n  name: nodegroup-template\nspec:\n  template:\n    metadata:\n      description: \"EKS Node Group configuration\"\n    spec:\n      module:\n        source: \"./internal/tf_module/eks_node_group\"\n      variables:\n        instance_types:\n          value: [\"${var.instance_type}\"]\n        disk_size:\n          value: \"${var.disk_size}\"\n```\n\n#### Apply Cluster Configuration\n\n```yaml\napiVersion: cluster.x-k8s.io/v1beta1\nkind: Cluster\nmetadata:\n  name: demo-cluster\nspec:\n  clusterNetwork:\n    services:\n      cidrBlocks: [\"10.96.0.0/12\"]\n    pods:\n      cidrBlocks: [\"192.168.0.0/16\"]\n  infrastructureRef:\n    apiVersion: infrastructure.cluster.x-k8s.io/v1beta1\n    kind: CAPTCluster\n    name: demo-cluster\n  controlPlaneRef:\n    apiVersion: controlplane.cluster.x-k8s.io/v1beta1\n    kind: CAPTControlPlane\n    name: demo-cluster\n```\n\nNote: WorkspaceTemplateApply resources are automatically created and managed by the controllers. You do not need to create them manually.\n\n## Best Practices\n\n### 1. Resource Management\n- Manage related resources in the same namespace\n- Use consistent naming conventions\n- Define clear dependencies between components\n- Regular configuration drift checks\n- Utilize ClusterClass for standardized deployments\n- Let controllers manage WorkspaceTemplateApply resources\n\n### 2. Security\n- Manage sensitive information as secrets\n- Follow the principle of least privilege for IAM configuration\n- Proper security group configuration\n- Implement secure network policies\n\n### 3. Operations\n- Separate configurations per environment\n- Utilize version control effectively\n- Monitor and manage component lifecycles\n- Regular security and compliance audits\n- Use ClusterClass for consistent deployments\n\n### 4. Template Management\n- Document template purposes and requirements\n- Version templates appropriately\n- Implement proper tagging strategies\n- Maintain backward compatibility\n- Leverage ClusterClass variables for flexibility\n- Use WorkspaceTemplate for infrastructure definitions\n- Let controllers handle WorkspaceTemplateApply lifecycle\n\n## Features\n\n### ClusterClass Support\n- Standardized cluster templates\n- Variable-based configuration\n- Reusable control plane templates\n- Consistent cluster deployments\n- Environment-specific customization\n\n### WorkspaceTemplate Management\n- Infrastructure as code using Terraform\n- Version control and metadata tracking\n- Secure secret management\n- Reusable infrastructure templates\n- Automatic WorkspaceTemplateApply management by controllers\n\n### Machine Management\n- Independent compute resource lifecycle\n- Flexible node group configuration\n- Support for multiple instance types\n- Automated scaling configuration\n- Integration with cluster autoscaling\n- Template-based node group management\n\n### VPC Management\n- Multi-AZ deployment\n- Public and private subnets\n- NAT Gateway configuration\n- EKS and Karpenter integration\n- VPC retention for shared infrastructure\n- Independent VPC lifecycle management\n\n### EKS Control Plane\n- Fargate profiles for system workloads\n- EKS Blueprints addons integration\n- CoreDNS, VPC-CNI, and Kube-proxy configuration\n- Karpenter setup for node management\n- Template-based configuration with ClusterClass\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Commit your changes\n4. Push to the branch\n5. Create a Pull Request\n\n## Releasing\n\nCAPT uses an automated release process through GitHub Actions. When creating a new release:\n\n1. Update the version number in relevant files (e.g., `VERSION`, `Chart.yaml`, etc.)\n2. Update the CHANGELOG.md file with the new version and its changes\n3. Create and push a new tag:\n   ```bash\n   # For Release Candidates\n   git tag -a v1.0.0-rc1 -m \"Release Candidate 1 for v1.0.0\"\n\n   # For Stable Releases\n   git tag -a v1.0.0 -m \"Release v1.0.0\"\n\n   git push origin \u003ctag-name\u003e\n   ```\n\nThe release workflow will automatically:\n- Build and push multi-architecture Docker images (amd64/arm64) to ghcr.io/appthrust/capt\n- Generate the capt.yaml installer\n- Create a GitHub release with:\n  - Release notes from CHANGELOG.md\n  - capt.yaml installer as an asset\n  - Links to the container images\n\nUsers can then:\n1. Download and apply the capt.yaml installer\n2. Or use the container images directly from ghcr.io/appthrust/capt\n\nNote: Release Candidates (RC) are tagged with `-rc` suffix and are primarily for testing. Production deployments should use stable releases.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappthrust%2Fcapt","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fappthrust%2Fcapt","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fappthrust%2Fcapt/lists"}