fluxcd · stefanprodan · Apr 8, 2024 · Apr 8, 2024
diff --git a/.github/workflows/tests.yaml b/.github/workflows/tests.yaml
@@ -6,6 +6,9 @@ on:
   pull_request:
     branches: [ main ]
 
+env:
+  TERRAFORM_VERSION: 1.7.5
+
 jobs:
   # Ensure project builds before running testing matrix
   build:
@@ -126,7 +129,7 @@ jobs:
       - name: Install Terraform
         uses: hashicorp/setup-terraform@a1502cd9e758c50496cc9ac5308c4843bcd56d36 # v3.0.0
         with:
-          terraform_version: '1.7.5'
+          terraform_version: "${{env.TERRAFORM_VERSION}}"
           terraform_wrapper: false
       - name: Apply Terraform
         run: |
@@ -191,7 +194,7 @@ jobs:
       - name: Install Terraform
         uses: hashicorp/setup-terraform@a1502cd9e758c50496cc9ac5308c4843bcd56d36 # v3.0.0
         with:
-          terraform_version: '1.7.5'
+          terraform_version: "${{env.TERRAFORM_VERSION}}"
           terraform_wrapper: false
       - name: Apply Terraform
         run: |
@@ -223,3 +226,66 @@ jobs:
             https://api.github.com/repos/fluxcd-testing/${{ steps.vars.outputs.test_repo_name }}
         env:
           GITHUB_TOKEN: ${{ secrets.GITPROVIDER_BOT_TOKEN }}
+  e2e-flux-bootstrap-with-github-pat:
+    runs-on: ubuntu-latest
+    needs: build
+    if: (github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository) && github.actor != 'dependabot[bot]'
+    steps:
+      - name: Checkout
+        uses: actions/checkout@b4ffde65f46336ab88eb53be808477a3936bae11 # v4.1.1
+      - name: Setup Go
+        uses: actions/setup-go@0c52d547c9bc32b1aa3301fd7a9cb496313a4491 # v5.0.0
+        with:
+          go-version-file: 'go.mod'
+          cache: true
+          cache-dependency-path: |
+            **/go.sum
+            **/go.mod
+      - name: Setup Flux CLI
+        uses: fluxcd/flux2/action@534684601ec8888beb0cc4f51117b59e97606c4d # v2.2.3
+      - name: Set outputs
+        id: vars
+        run: |
+          REPOSITORY_NAME=${{ github.event.repository.name }}
+          BRANCH_NAME=${GITHUB_REF##*/}
+          COMMIT_SHA=$(git rev-parse HEAD)
+          PSEUDO_RAND_SUFFIX=$(echo "${BRANCH_NAME}-${COMMIT_SHA}" | shasum | awk '{print $1}')
+          TEST_REPO_NAME="${REPOSITORY_NAME}-${PSEUDO_RAND_SUFFIX}-using-pat"
+          echo "test_repo_name=$TEST_REPO_NAME" >> $GITHUB_OUTPUT
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITPROVIDER_BOT_TOKEN }}
+      - name: Install Terraform
+        uses: hashicorp/setup-terraform@a1502cd9e758c50496cc9ac5308c4843bcd56d36 # v3.0.0
+        with:
+          terraform_version: "${{env.TERRAFORM_VERSION}}"
+          terraform_wrapper: false
+      - name: Apply Terraform
+        run: |
+          make build
+          make terraformrc
+          export TF_CLI_CONFIG_FILE="${PWD}/.terraformrc"
+          cd examples/github-via-pat
+          terraform init
+          terraform apply -auto-approve -var "github_token=${GITHUB_TOKEN}" -var "github_org=fluxcd-testing" -var "github_repository=${{ steps.vars.outputs.test_repo_name }}"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITPROVIDER_BOT_TOKEN }}
+      - name: Health check Flux
+        run: flux check
+      - name: Destroy Terraform
+        run: |
+          cd examples/github-via-pat
+          terraform destroy -auto-approve -var "github_token=${GITHUB_TOKEN}" -var "github_org=fluxcd-testing" -var "github_repository=${{ steps.vars.outputs.test_repo_name }}"
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITPROVIDER_BOT_TOKEN }}
+      - name: Delete repository
+        if: ${{ always() }}
+        continue-on-error: true
+        run: |
+          curl \
+            -X DELETE \
+            -H "Accept: application/vnd.github.v3+json" \
+            -H "Authorization: token ${GITHUB_TOKEN}" \
+            --fail --silent \
+            https://api.github.com/repos/fluxcd-testing/${{ steps.vars.outputs.test_repo_name }}
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITPROVIDER_BOT_TOKEN }}
diff --git a/README.md b/README.md
@@ -1,47 +1,69 @@
-# Terraform Provider Flux
+# Flux provider for Terraform
 
 [![tests](https://github.com/fluxcd/terraform-provider-flux/workflows/tests/badge.svg)](https://github.com/fluxcd/terraform-provider-flux/actions)
 [![report](https://goreportcard.com/badge/github.com/fluxcd/terraform-provider-flux)](https://goreportcard.com/report/github.com/fluxcd/terraform-provider-flux)
 [![license](https://img.shields.io/github/license/fluxcd/terraform-provider-flux.svg)](https://github.com/fluxcd/terraform-provider-flux/blob/main/LICENSE)
 [![release](https://img.shields.io/github/release/fluxcd/terraform-provider-flux/all.svg)](https://github.com/fluxcd/terraform-provider-flux/releases)
 
-This is the Terraform provider for Flux v2. The provider allows you to install Flux on Kubernetes and configure it to reconcile the cluster state from a Git repository.
-
-## Get Started
-
-Below is an example for how to bootstrap a Kubernetes cluster with Flux.
-Refer to [registry.terraform.io](https://registry.terraform.io/providers/fluxcd/flux/latest)
-for detailed configuration documentation.
-
-```hcl
-provider "flux" {
-  kubernetes = {
-    config_path = "~/.kube/config"
-  }
-  git = {
-    url  = var.repository_ssh_url
-    ssh = {
-      username    = "git"
-      private_key = var.private_key_pem
-    }
-  }
-}
-
-resource "flux_bootstrap_git" "this" {
-  path = "clusters/my-cluster"
-}
-```
+## Overview
+The Flux provider for Terraform is a plugin that enables bootstrapping of your Kubernetes cluster using [Flux v2](https://github.com/fluxcd/flux2/tree/main).
+
+Please note: We take security and our users' trust very seriously. If you believe you have found a security issue in the Terraform Flux Provider, please follow the policy located [here](https://github.com/fluxcd/terraform-provider-flux/security/policy).
+
+## Documentation
+All documentation is available on the [Terraform provider website](https://registry.terraform.io/providers/fluxcd/flux/latest/docs).
 
 ## Guides
 
 The following guides are available to help you use the provider:
 
-- [Configuration using a Github repository via SSH](examples/github-via-ssh)
-- [Configuration using a Github repository via SSH and GPG](examples/github-via-ssh-with-gpg)
-- [Configuration using a Github repository via SSH with flux customizations](examples/github-with-customizations)
-- [Configuration using a Github repository via SSH and GPG with inline flux customizations](examples/github-with-inline-customizations)
-- [Configuration using a Gitlab repository via SSH](examples/gitlab-via-ssh)
-- [Configuration using a Gitlab repository via SSH and GPG](examples/gitlab-via-ssh-with-gpg)
-- [Configuration using a Helm Release and not the flux_bootstrap_git resource](examples/helm-install) **
+- [Bootstrapping a cluster using a GitHub repository using a personal access token (PAT)](examples/github-via-pat)
+- [Bootstrapping a cluster using a GitHub repository via SSH](examples/github-via-ssh)
+- [Bootstrapping a cluster using a GitHub repository via SSH and GPG](examples/github-via-ssh-with-gpg)
+- [Bootstrapping a cluster using a GitHub repository via SSH with flux customizations](examples/github-with-customizations)
+- [Bootstrapping a cluster using a GitHub repository via SSH and GPG with inline flux customizations](examples/github-with-inline-customizations)
+- [Bootstrapping a cluster using a Gitlab repository via SSH](examples/gitlab-via-ssh)
+- [Bootstrapping a cluster using a Gitlab repository via SSH and GPG](examples/gitlab-via-ssh-with-gpg)
+- [Bootstrapping a cluster using a Helm Release and not the flux_bootstrap_git resource](examples/helm-install) **
 
 ** This is the recommended approach if you do not want to perform initial flux bootstrapping.
+
+## Requirements
+
+- [Terraform](https://www.terraform.io/downloads.html) 1.5.x or newer
+- [Go](https://golang.org/doc/install) 1.22 (to build the provider plugin)
+
+## Contributing to the provider
+
+The Flux Provider for Terraform is the work of many contributors. We appreciate your help!
+
+To contribute, please read the [contribution guidelines](CONTRIBUTING.md). You may also [report an issue](https://github.com/fluxcd/terraform-provider-flux/issues/new/choose).
+
+## Community
+
+Need help or want to contribute? Please see the links below. The Flux project is always looking for
+new contributors and there are a multitude of ways to get involved.
+
+- Getting Started?
+    - Look at our [Get Started guide](https://fluxcd.io/flux/get-started/) and give us feedback
+- Need help?
+    - First: Ask questions on our [GH Discussions page](https://github.com/fluxcd/flux2/discussions).
+    - Second: Talk to us in the #flux channel on [CNCF Slack](https://slack.cncf.io/).
+    - Please follow our [Support Guidelines](https://fluxcd.io/support/)
+      (in short: be nice, be respectful of volunteers' time, understand that maintainers and
+      contributors cannot respond to all DMs, and keep discussions in the public #flux channel as much as possible).
+- Have feature proposals or want to contribute?
+    - Propose features on our [GitHub Discussions page](https://github.com/fluxcd/flux2/discussions).
+    - Join our upcoming dev meetings ([meeting access and agenda](https://docs.google.com/document/d/1l_M0om0qUEN_NNiGgpqJ2tvsF2iioHkaARDeh6b70B0/view)).
+    - [Join the flux-dev mailing list](https://lists.cncf.io/g/cncf-flux-dev).
+    - Check out [how to contribute](CONTRIBUTING.md) to the project.
+    - Check out the [project roadmap](https://fluxcd.io/roadmap/).
+
+### Events
+
+Check out our **[events calendar](https://fluxcd.io/#calendar)**,
+both with upcoming talks, events and meetings you can attend.
+Or view the **[resources section](https://fluxcd.io/resources)**
+with past events videos you can watch.
+
+We look forward to seeing you with us!
diff --git a/docs/index.md b/docs/index.md
@@ -15,15 +15,14 @@ The provider needs to be configured with Kubernetes credentials to be used.
 
 The following examples are available to help you use the provider:
 
-- [Configuration using a Github repository via SSH](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/github-via-ssh)
-- [Configuration using a Github repository via SSH and GPG](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/github-via-ssh-with-gpg)
-- [Configuration using a Github repository via SSH with flux customizations](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/github-with-customizations)
-- [Configuration using a Github repository via SSH and GPG with inline flux customizations](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/github-with-inline-customizations)
-- [Configuration using a Gitlab repository via SSH](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/gitlab-via-ssh)
-- [Configuration using a Gitlab repository via SSH and GPG](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/gitlab-via-ssh-with-gpg)
-- [Configuration using a Helm Release and not the flux_bootstrap_git resource](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/helm-install) **
-
-** This is the recommended approach if you do not want to perform initial flux bootstrapping.
+- [Bootstrapping a cluster using a GitHub repository and a personal access token (PAT)](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/github-via-pat)
+- [Bootstrapping a cluster using a GitHub repository via SSH](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/github-via-ssh)
+- [Bootstrapping a cluster using a GitHub repository via SSH and GPG](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/github-via-ssh-with-gpg)
+- [Bootstrapping a cluster using a GitHub repository via SSH with flux customizations](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/github-with-customizations)
+- [Bootstrapping a cluster using a GitHub repository via SSH and GPG with inline flux customizations](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/github-with-inline-customizations)
+- [Bootstrapping a cluster using a Gitlab repository via SSH](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/gitlab-via-ssh)
+- [Bootstrapping a cluster using a Gitlab repository via SSH and GPG](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/gitlab-via-ssh-with-gpg)
+- [Bootstrapping a cluster using a Helm Release](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/helm-install)
 
 ## Provider Configuration
 

diff --git a/docs/resources/bootstrap_git.md b/docs/resources/bootstrap_git.md
@@ -13,13 +13,14 @@ Commits Flux components to a Git repository and configures a Kubernetes cluster
 
 The following examples are available to help you use the provider:
 
-- [Configuration using a Github repository via SSH](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/github-via-ssh)
-- [Configuration using a Github repository via SSH and GPG](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/github-via-ssh-with-gpg)
-- [Configuration using a Github repository via SSH with flux customizations](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/github-with-customizations)
-- [Configuration using a Github repository via SSH and GPG with inline flux customizations](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/github-with-inline-customizations)
-- [Configuration using a Gitlab repository via SSH](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/gitlab-via-ssh)
-- [Configuration using a Gitlab repository via SSH and GPG](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/gitlab-via-ssh-with-gpg)
-- [Configuration using a Helm Release and not the flux_bootstrap_git resource]((https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/helm-install) that is the recommended approach if you do not want to perform bootstrapping.
+- [Bootstrapping a cluster using a GitHub repository and a personal access token (PAT)](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/github-via-pat)
+- [Bootstrapping a cluster using a GitHub repository via SSH](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/github-via-ssh)
+- [Bootstrapping a cluster using a GitHub repository via SSH and GPG](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/github-via-ssh-with-gpg)
+- [Bootstrapping a cluster using a GitHub repository via SSH with flux customizations](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/github-with-customizations)
+- [Bootstrapping a cluster using a GitHub repository via SSH and GPG with inline flux customizations](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/github-with-inline-customizations)
+- [Bootstrapping a cluster using a Gitlab repository via SSH](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/gitlab-via-ssh)
+- [Bootstrapping a cluster using a Gitlab repository via SSH and GPG](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/gitlab-via-ssh-with-gpg)
+- [Bootstrapping a cluster using a Helm Release](https://github.com/fluxcd/terraform-provider-flux/tree/main/examples/helm-install)
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

diff --git a/examples/github-via-pat/README.md b/examples/github-via-pat/README.md
@@ -0,0 +1,50 @@
+# GitHub via SSH
+
+The example demonstrates how to bootstrap a KinD cluster with Flux using a GitHub repository via a [personal access token (PAT)](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens).
+
+We recommend creating a fine-gained PAT and dedicated Flux user, for more information see [here](https://fluxcd.io/flux/installation/bootstrap/github/#github-organization)
+
+Note: The GitHub repository is created and auto initialised ready for Flux to use.
+
+<!-- BEGINNING OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
+## Requirements
+
+| Name | Version |
+|------|---------|
+| <a name="requirement_terraform"></a> [terraform](#requirement\_terraform) | >= 1.7.0 |
+| <a name="requirement_flux"></a> [flux](#requirement\_flux) | >= 1.2 |
+| <a name="requirement_github"></a> [github](#requirement\_github) | >= 6.1 |
+| <a name="requirement_kind"></a> [kind](#requirement\_kind) | >= 0.4 |
+
+## Providers
+
+| Name | Version |
+|------|---------|
+| <a name="provider_flux"></a> [flux](#provider\_flux) | >= 1.2 |
+| <a name="provider_github"></a> [github](#provider\_github) | >= 6.1 |
+| <a name="provider_kind"></a> [kind](#provider\_kind) | >= 0.4 |
+
+## Modules
+
+No modules.
+
+## Resources
+
+| Name | Type |
+|------|------|
+| [flux_bootstrap_git.this](https://registry.terraform.io/providers/fluxcd/flux/latest/docs/resources/bootstrap_git) | resource |
+| [github_repository.this](https://registry.terraform.io/providers/integrations/github/latest/docs/resources/repository) | resource |
+| [kind_cluster.this](https://registry.terraform.io/providers/tehcyx/kind/latest/docs/resources/cluster) | resource |
+
+## Inputs
+
+| Name | Description | Type | Default | Required |
+|------|-------------|------|---------|:--------:|
+| <a name="input_github_org"></a> [github\_org](#input\_github\_org) | GitHub organization | `string` | `""` | no |
+| <a name="input_github_repository"></a> [github\_repository](#input\_github\_repository) | GitHub repository | `string` | `""` | no |
+| <a name="input_github_token"></a> [github\_token](#input\_github\_token) | GitHub token | `string` | `""` | no |
+
+## Outputs
+
+No outputs.
+<!-- END OF PRE-COMMIT-TERRAFORM DOCS HOOK -->
diff --git a/examples/github-via-pat/main.tf b/examples/github-via-pat/main.tf
@@ -0,0 +1,47 @@
+terraform {
+  required_version = ">= 1.7.0"
+
+  required_providers {
+    flux = {
+      source  = "fluxcd/flux"
+      version = ">= 1.2"
+    }
+    github = {
+      source  = "integrations/github"
+      version = ">= 6.1"
+    }
+    kind = {
+      source  = "tehcyx/kind"
+      version = ">= 0.4"
+    }
+  }
+}
+
+# ==========================================
+# Construct KinD cluster
+# ==========================================
+
+resource "kind_cluster" "this" {
+  name = "flux-e2e"
+}
+
+# ==========================================
+# Initialise a Github project
+# ==========================================
+
+resource "github_repository" "this" {
+  name        = var.github_repository
+  description = var.github_repository
+  visibility  = "public"
+  auto_init   = true # This is extremely important as flux_bootstrap_git will not work without a repository that has been initialised
+}
+
+# ==========================================
+# Bootstrap KinD cluster
+# ==========================================
+
+resource "flux_bootstrap_git" "this" {
+  depends_on = [github_repository.this]
+
+  path = "clusters/my-cluster"
+}
diff --git a/examples/github-via-pat/outputs.tf b/examples/github-via-pat/outputs.tf
diff --git a/examples/github-via-pat/providers.tf b/examples/github-via-pat/providers.tf
@@ -0,0 +1,22 @@
+provider "flux" {
+  kubernetes = {
+    host                   = kind_cluster.this.endpoint
+    client_certificate     = kind_cluster.this.client_certificate
+    client_key             = kind_cluster.this.client_key
+    cluster_ca_certificate = kind_cluster.this.cluster_ca_certificate
+  }
+  git = {
+    url = "https://github.com/${var.github_org}/${var.github_repository}.git"
+    http = {
+      username    = "git" # This can be any string when using a personal access token
+      private_key = var.github_token
+    }
+  }
+}
+
+provider "github" {
+  owner = var.github_org
+  token = var.github_token
+}
+
+provider "kind" {}
diff --git a/examples/github-via-pat/variables.tf b/examples/github-via-pat/variables.tf
@@ -0,0 +1,18 @@
+variable "github_token" {
+  description = "GitHub token"
+  sensitive   = true
+  type        = string
+  default     = ""
+}
+
+variable "github_org" {
+  description = "GitHub organization"
+  type        = string
+  default     = ""
+}
+
+variable "github_repository" {
+  description = "GitHub repository"
+  type        = string
+  default     = ""
+}