docs: Ambiguous "datasource is used to get a reference to the repository"

[Mateusz Łoskot]

The current https://registry.terraform.io/providers/fluxcd/flux/latest/docs/guides/github says:

terraform-provider-flux/docs/guides/github.md

Line 62 in fa794b3

 The GitHub repository is created separatly so a datasource is used to get a reference to the repository. Creating GitHub repositories with Terraform is generally not a good idea as they could easily be removed. Additionally it is not possible to use the same repository for multiple environments if the repository is created with Terraform. 

but there is no use of the actual github_repository or any other data source in the guide.

The guide only refers to (one) GitHub provider resource:

terraform-provider-flux/docs/guides/github.md

Lines 75 to 77 in fa794b3

 resource "github_repository_deploy_key" "this" { 
   title      = "Flux" 
   repository = var.github_repository 

IMO, the sentence referenced at the beginning of this issue above is confusing.

BTW, this issue seems to also apply to the GitLab guide

terraform-provider-flux/docs/guides/gitlab.md

Line 63 in fa794b3

 The GitLab repository is created separatly so a datasource is used to get a reference to the repository. Creating GitLab repositories with Terraform is generally not a good idea as they could easily be removed. Additionally it is not possible to use the same repository for multiple environments if the repository is created with Terraform. 

I guess, the datasource reference may come from some old version of the examples, like in here

terraform-provider-flux/examples/multi-env/main.tf

Lines 17 to 19 in fa794b3

 data "github_repository" "main" { 
   name = var.repository_name 
 } 

[Steven Wade]

@mloskot the example is valid as the github_repository_deploy_key and gitlab_deploy_key are deploy keys added to the Github or Gitlab repositories.

Without these, flux would not be able to connect to the repositories in question within the provider configuration (see below):

provider "flux" {
  git = {
    url = "ssh://[e-mail]/${data.gitlab_project.this.path_with_namespace}.git"
    ssh = {
      username    = "git"
      private_key = tls_private_key.flux.private_key_pem
    }
  }
}

The private_key value above is the same private key used as the deploy key for the repository.

[Steven Wade]

I thought this may explain it better ...

1. We create a private key
2. That private key is used by the deploy key
3. That deploy key is associated with a repository (either github or gitlab)
4. The flux provider git configuration uses the same private key and can therefore access the repo.

[Steven Wade]

Please let me know if this makes sense, if it does I will create a PR to add some comments to the terraform code.

[Mateusz Łoskot]

@swade1987

the example is valid (...)

I did not suggest the example is not valid.
I only complained about the description accompanying the example as being confusing:

The GitHub repository is created separatly so a datasource is used
to get a reference to the repository.

and the example does not make use of any data source, what I explained in my report above.

Although I did grasp the idea behind use of the keys and the overall workflow, thank you very much for the further explanation.

[Steven Wade]

@mloskot I am glad we managed to resolve your issue, are you happy that we close this issue?