[Enhancement]: Improve provider documentation

[swade1987]

Description

I want to improve the provider documentation on the Terraform registry website.
Please add comments on what you would like covered.

Affected Resource(s) and/or Data Source(s)

No response

Potential Terraform Configuration

No response

References

⚠️ Warning ⚠️
Please note that the new documentation (once released) will be the current contents of the docs directory here.
Please use this directory's contents when making suggestions.
I have deleted all guides and have created a suite of new examples available here

Would you like to implement a fix?

Yes

[bwestover]

Thanks for asking for input. Apologies if this is not the right place for this 😊

When looking at the current example in the docs directory I noticed that they all seem create a new Git repository. This is great for a working example 👍 (it also creates a kind cluster)

I have a mono-repo with several clusters already set up with Flux (using the CLI). Now I'm looking to use flux_bootstrap_git to add a new cluster to this existing repository (in a new directory I've set up for this cluster). An example on how to use the provider to bootstrap a new cluster with an existing repository would be helpful for me, and hopefully others as well.

[swade1987]

@bwestover

Firstly, apologies for the slow response.

Please see the example here. You can follow this but must remove the following block that creates the repository.

# ==========================================
# Initialise a Github project
# ==========================================

resource "github_repository" "this" {
  name        = var.github_repository
  description = var.github_repository
  visibility  = "private"
  auto_init   = true # This is extremely important as flux_bootstrap_git will not work without a repository that has been initialised
}

You still need a token or SSH key with write access to Git.

[balonik]

@bwestover if you already have Git repository you can skip all the GitHub/GitLab/others related resources and just bootstrap Flux. The minimal code using http with GitLab could look like this.

provider "flux" {
  kubernetes = {
    # setup authentication here
  }
  git = {
    url                     = "https://gitlab.com/mygroup/myproject.git"
    http = {
      username = ...
      password = ...
    }
  }
}

resource "flux_bootstrap_git" "flux" {
  path                   = "<path to existing directory>"
}

[bwestover]

Thanks for the responses 🙇 - I have this working now.

To summarize the parts I was missing after reading the current docs and examples:

• Whether or not this provider needs API access to the repo (i.e. was the "github" provider in the examples incidental or is it a requirement)

  • In the GitHub examples creating a new repo used the "github" provider and token, but the Flux provider doesn't need it otherwise.
  • The provider handles the installation of Flux and configures it to talk to the repo. It does not handle the repo creation (contrasted with the Flux CLI which will create the repo if it doesn't exist). It can and will work with a pre-existing repo just fine.

• Whether the path in the repo must exist already

  • The docs for the path variable say "... when specified the cluster sync will be scoped to this path", but it doesn't explicitly mention that it will be created if it doesn't exist. I assume it MUST create it since it works with brand new (empty) repositories)

• How the authentication will be set up in the cluster

  • My frame of reference here is the Flux bootstrap CLI for GitHub (perhaps other integrations work differently). I've seen this work two ways:
    • If I pass both --token-auth and --personal flags I must provide a PAT, and that PAT gets stored in the "flux-system" secret and is used to make commits to the repo as part of the initial bootrapping.
    • If I pass only --token-auth then it is assumed that it is an organization owned repository. It uses the PAT to make commits to the repo during bootstrapping. It also creates a read-only deploy key, and stores that in the "flux-system" secret.

  TL;DR - In one case it will set up a deploy key and store it, and in the other case it just stores the PAT, however in BOTH cases it uses the PAT to make commits. What is the behavior of the Flux provider? So far it seems like however I set up auth in the Flux provider (in the nested git schema), is what gets stored on the cluster in the "flux-system" secret. If I want/need deploy keys, I need to set those up separately with Terraform (like in the github-via-ssh example.

FWIW, I don't disagree with any of these choices 😸 It seems like in Terraform we want separation of concerns vs the CLI which handles more parts of the process itself (e.g. creating deploy tokens, creating repo if necessary). I wanted to point out where my thinking was when trying to onboard to this provider in case it helps with documentation choices/efforts. Thanks for all you do here!

[swade1987]

@bwestover

I love this, and thanks for the detailed reply. It's much appreciated.

I will definitely incorporate these into my next PR and "@" you to review it prior to merging.

[stefanprodan]

If I pass only --token-auth then it is assumed that it is an organization owned repository. It uses the PAT to make commits to the repo during bootstrapping. It also creates a read-only deploy key, and stores that in the "flux-system" secret.

This is not the case, flux bootstrap --token-auth will create a secret with the token in the cluster and will configure Flux source-controller to clone over HTTP/S.