DOCSEARCHbyAlgolia
Submit Docs

Rancher2 Terraform Provider

repository·main·Indexed 43 days ago

https://github.com/rancher/terraform-provider-rancher2

Terraform provider for managing Rancher v2 resources. Includes documentation on building the provider from source (requiring Go 1.25+ and Terraform >= 1.5.0), version alignment with Rancher minor versions, and deployment examples for AWS, including single-server, three-node HA, and production-ready clusters.

Tokens
105.2K
Snippets
256
Records
484
Agent score
54%

What's inside Rancher2 Terraform Provider

  1. Overview of coding standards and compliance framework

    main

    The project enforces a multi-layered compliance framework to ensure code is readable, secure, and idiomatic. The standards are organized into four main pillars:

    1. Core Development Languages: Specific standards for Go (error handling, context propagation, timeouts) and Terraform (naming conventions, variable validations).
    2. CI/CD & Automation: Standards for GitHub Actions Workflows (least-privilege, action pinning by SHA), GitHub Scripts (JavaScript-based automation), and Shell Scripts (strict Bash rules like set -euo pipefail).
    3. Documentation & Architecture: Standards for Architectural Blueprints (lifecycle of planning) and Documentation Styles (Diátaxis-compliant technical writing).
    4. Code Review: Automated validation via the review_agent using specific GitHub Copilot Review Guidelines.

  2. Use the rancher2_cluster resource

    main

    The rancher2_cluster resource provides a Rancher v2 Cluster resource. It is primarily used to create imported Clusters for Rancher v2 environments and retrieve their information (such as registration commands).

    Important Considerations:

    • RKE1 Deprecation: Rancher Kubernetes Engine (RKE/RKE1) reached end of life on July 31, 2025. Rancher versions 2.12.0 and later do not support provisioning or managing downstream RKE1 clusters. It is recommended to use RKE2.
    • Resource Selection: For creating node-driver and custom RKE2 or K3s Clusters, use the Rancher v2 Cluster v2 resource instead of rancher2_cluster.
    • Resetting Optional/Computed Arguments: If you define an optional/computed argument and later want to reset it, removing it from the .tf file will NOT reset its value. To reset it, set the definition to an empty or false object (e.g., cloud_provider {} or name = "").
    resource "rancher2_cluster" "foo-imported" {
  name = "foo-imported"
  description = "Foo rancher2 imported cluster"
}

  3. Manage rancher2_machine_config_v2 resources

    main

    The rancher2_machine_config_v2 resource allows you to create and manage Machine Config v2 for Rancher v2. This resource is available for Rancher v2.6.0 and above. It supports multiple cloud providers, allowing you to define infrastructure configurations for different environments.

    Supported Cloud Providers:

    • amazonec2
    • azure
    • digitalocean
    • harvester
    • linode
    • nutanix
    • openstack
    • vsphere
    • google (Supported from Rancher v2.12.0 and above)

    Note: You can only specify one cloud provider configuration block per resource. Using multiple provider blocks (e.g., both amazonec2_config and azure_config) will cause a conflict.

    resource "rancher2_machine_config_v2" "foo" {
  generate_name = "test-foo"
  amazonec2_config {
    ami =  "<AMI_ID>"
    region = "<REGION>"
    security_group = [<AWS_SG>]
    subnet_id = "<SUBNET_ID>"
    vpc_id = "<VPC_ID>"
    zone = "<ZONE>"
  }
}

  4. Use the rancher2_cluster_v2 resource to manage RKE2 and K3s clusters

    main

    The rancher2_cluster_v2 resource allows you to create and manage node-driver and custom RKE2 or K3s clusters within Rancher v2 environments. This resource is suitable for managing clusters where Rancher handles the provisioning via node drivers or custom configurations.

    Requirements:

    • Rancher version: v2.6.0 or above.

    Important Distinction: If you are trying to register an existing, standalone Kubernetes cluster into Rancher (importing it), do not use rancher2_cluster_v2. Instead, use the standard rancher2_cluster resource.

    # Example usage will be provided in subsequent segments

  5. Architectural pattern for GitHub Workflows

    main

    GitHub Workflows in this repository follow an 'Orchestrate, Don't Execute' pattern. Workflows are intended to be thin orchestration layers that declare the execution model, while all non-trivial logic is extracted into dedicated, testable scripts.

    Key components:

    • Orchestrators: GitHub Action YAML files that define jobs and call scripts.
    • Implementation Scripts: JavaScript or Bash scripts located in .github/workflows/scripts/ that contain the actual logic (e.g., Git tagging, manifest scans, PR validation).

    This separation allows for local unit testing of automation logic without requiring a GitHub Actions runner environment.

  6. How Automated Release Candidate (RC) Tagging works

    main

    When the release-please workflow triggers, it calculates a target version and generates intermediate Release Candidate (RC) tags for binary pre-releases.

    • Tag Calculation: The script .github/workflows/scripts/create-push-rc-tag.js identifies the largest existing RC suffix for the target base version (e.g., v1.2.3-rc.x), increments the count (e.g., v1.2.3-rc.0 becomes v1.2.3-rc.1), and pushes the new tag to the active context.sha.
    • Implementation: Tag creation is performed programmatically via the GitHub REST API (github.rest.git.createRef) using the runner's authenticated token. This ensures bot-attributed releases without requiring local SSH or GPG keychain dependencies on the GitHub Actions runner.

  7. Understand the Gated 4-Phase Lifecycle

    main

    The Agentic Framework uses a structured 4-phase lifecycle to manage human-agent collaboration, ensuring all changes are vetted through three specific gates. The phases are Plan, Implement, Review, and Commit.

    The Three Gates

    1. Gate 1: Planning Gate (User-Facing)

      • Transition: Plan $\rightarrow$ Implement.
      • Mechanism: Requires macOS Touch ID to GPG-sign the strategy checklist, creating plan-approval.json.
      • Effect: Authorizes the agent to perform autonomous file modifications, compilation, and testing.

    2. Gate 2: Quality Gate (Programmatic)

      • Transition: Implement $\rightarrow$ Review.
      • Mechanism: Automatically verifies that local unit and integration tests pass. It then delegates an automated code review to a sandboxed review_agent to generate a review-approval.json signature.

    3. Gate 3: Commit Gate (User-Facing)

      • Transition: Review $\rightarrow$ Commit.
      • Mechanism: Displays the live unstaged Git diff in chat and requests approval for a Conventional Commit message. Requires macOS Touch ID for physical sign-off, creating user-approval.json.
      • Effect: Automatically stages files, commits with the signature, pushes, and opens a Draft PR on GitHub.
    [ Plan Phase ]
             │
             ▼
 🔒 Gate 1: Planning Gate (User-Facing / GPG Touch ID)
             │
             ▼
       [ Implement Phase (Autonomous) ]
             │
             ▼
       [ Review Phase ]
             │
             ▼
 🔒 Gate 2: Quality Gate (Programmatic / Test & Subagent)
             │
             ▼
       [ Commit Phase ]
             │
             ▼
 🔒 Gate 3: Commit Gate (User-Facing / GPG Touch ID)

  8. Understand Manifest-Driven Automation with release-please

    main

    Versioning and changelog generation are automated using release-please in manifest mode. The automation works by scanning Conventional Commit squash-merge titles on the main branch to compute the appropriate Semantic Versioning (SemVer) increment.

    Key workflow steps:

    1. release-please maintains a running "Release PR."
    2. When a developer's changes are merged, the tool updates the Release PR and generates an automated changelog.
    3. Once the Release PR is merged, the system automatically tags the release and triggers the compilation pipeline.

  9. Follow the Blueprint Directory Structure & Nomenclature

    main

    To maintain scalability, the project uses a two-tiered documentation pattern within docs/development/. When contributing or looking for technical details, follow this structure:

    1. Topic Overview (docs/development/<Topic>.md)

    Used for high-level domain abstracts (e.g., AgenticFramework.md). Required Sections:

    • Purpose: High-level domain abstract.
    • Modular Architectural Blueprints Map: Links to individual Component Specifications within that domain.

    2. Component Specification (docs/development/<Topic>/<Component>.md)

    Used for detailed technical designs of specific subsystems or workflows. Required Sections:

    • Abstract: Concise explanation of goals and responsibilities.
    • Architectural Design / Technical Specification: Deep dive into mechanics, data flows, and configuration.
    • Standing Implementation Decisions: Long-term design choices, trade-offs, and standing parameters.

  10. How Conventional Commits drive version bumps

    main

    Release Please uses the Conventional Commits specification to determine version increments and changelog entries:

    • fix:: Triggers a Patch version bump (1.0.0 -> 1.0.1).
    • feat:: Triggers a Minor version bump (1.0.0 -> 1.1.0).
    • ! (Breaking Change): Appending ! to the type (e.g., feat!:) or including BREAKING CHANGE: in the commit footer triggers a Major version bump (1.0.0 -> 2.0.0).
    • Force Version: To override automatic calculation, add Release-As: x.y.z to the commit body.

  11. Understand the Review Subagent's role and constraints

    main

    The review_agent is a hardened, read-only AI agent designed for automated pre-commit code audits. It performs line-by-line checks on workspace diffs to ensure compliance with coding standards and security safeguards.

    Key Constraints:

    • Read-Only Access: To maintain a zero-trust security model, the agent is strictly prohibited from using file-modifying tools (e.g., replace, write_file) or shell-execution tools (e.g., run_shell_command).
    • Allowed Tools: It interacts with the workspace exclusively via read_file and glob.
    • Configuration: Its custom model definition is stored at .gemini/agents/review_agent.md.

  12. Operational logic of the Boilerplate Sync skill

    main

    The synchronization process follows a hermetic, manifest-driven sequence to ensure minimal footprint and security:

    1. Manifest Parsing: Uses jq to validate .template_repo and the files array.
    2. Sandbox Creation: Creates a temporary workspace using mktemp -d (typically under /tmp/boilerplate-sync-XXXXXX).
    3. Optimized Fetching: Performs a git clone --depth 1 --no-checkout of the remote repository to minimize network and disk usage, checking out only the files explicitly mapped in the manifest.
    4. Execution: Performs the requested --diff, --pull, or --push operation.
    5. Cleanup: Uses an exit trap (trap 'cleanup' EXIT) to ensure the temporary workspace is deleted regardless of whether the process succeeds or fails.