Adding how-to guide for tf private registry for recipes (#1073)

* Adding how-to guide for tf private registry for recipes Signed-off-by: jasonviviano <[email protected]> * Addressed feedback with Vishwanath's help. Signed-off-by: jasonviviano <[email protected]> * Fixed snippet Signed-off-by: jasonviviano <[email protected]> * Apply suggestions from code review Co-authored-by: Will <[email protected]> Signed-off-by: jasonviviano <[email protected]> * Apply suggestions from code review Co-authored-by: Aaron Crawfis <[email protected]> Signed-off-by: jasonviviano <[email protected]> * Addressed feedback on howto-private-registry Signed-off-by: jasonviviano <[email protected]> * Apply suggestions from code review Co-authored-by: Aaron Crawfis <[email protected]> Signed-off-by: jasonviviano <[email protected]> * Apply suggestions from code review Co-authored-by: Vishwanath Hiremath <[email protected]> Signed-off-by: jasonviviano <[email protected]> * Addressed certain changes to the steps of the guide. Signed-off-by: jasonviviano <[email protected]> * Fixed naming. Signed-off-by: jasonviviano <[email protected]> * Addressed feedback Signed-off-by: jasonviviano <[email protected]> * Spellcheck fix Signed-off-by: jasonviviano <[email protected]> * Apply suggestions from code review Co-authored-by: Aaron Crawfis <[email protected]> Signed-off-by: jasonviviano <[email protected]> * Apply suggestions from code review Signed-off-by: jasonviviano <[email protected]> * Fixed snippet render Signed-off-by: jasonviviano <[email protected]> * Moved folder Signed-off-by: jasonviviano <[email protected]> * Added a note linking to the limitations page Signed-off-by: jasonviviano <[email protected]> * Added an explanation to the `resource` property. Signed-off-by: jasonviviano <[email protected]> * Fixed spelling Signed-off-by: jasonviviano <[email protected]> * Apply suggestions from code review Co-authored-by: Aaron Crawfis <[email protected]> Signed-off-by: jasonviviano <[email protected]> * Addressed feedback on how-to guide Signed-off-by: jasonviviano <[email protected]> * Spellcheck fix Signed-off-by: jasonviviano <[email protected]> --------- Signed-off-by: jasonviviano <[email protected]> Co-authored-by: Will <[email protected]> Co-authored-by: Aaron Crawfis <[email protected]> Co-authored-by: Vishwanath Hiremath <[email protected]>
radius-project · Mar 11, 2024 · 84f0979 · 84f0979
1 parent 7a73a1d
commit 84f0979
Show file tree

Hide file tree

Showing 5 changed files with 189 additions and 0 deletions.
diff --git a/.github/config/en-custom.txt b/.github/config/en-custom.txt
@@ -235,6 +235,7 @@ lifecycles
 linkTitle
 linter
 linux
+lineNos
 liveness
 livenessProbe
 localWorkspace
@@ -311,6 +312,7 @@ redoc
 resourceGroup
 replacePrefix
 repo
+repos
 resourceGroupName
 RecipeSpecified
 resourceId
@@ -981,6 +983,7 @@ learnings
 architected
 customizable
 Gitops
+GitLab
 OSS
 SRE
 SREs

diff --git a/docs/content/guides/recipes/howto-private-registry/index.md b/docs/content/guides/recipes/howto-private-registry/index.md
@@ -0,0 +1,81 @@
+---
+type: docs
+title: "How-To: Pull Terraform modules from private git repositories"
+linkTitle: "Private git repos"
+description: "Learn how to setup your Radius environment to pull Terraform Recipe templates from a private git repository."
+weight: 500
+categories: "How-To"
+tags: ["recipes", "terraform"]
+---
+
+This how-to guide will describe how to:
+
+- Configure a Radius Environment to be able to pull Terraform Recipe templates from a private git repository.
+
+### Prerequisites
+
+Before you get started, you'll need to make sure you have the following tools and resources:
+
+- [rad CLI]({{< ref "installation#step-1-install-the-rad-cli" >}})
+- [Radius Bicep VSCode extension]({{< ref "installation#step-2-install-the-vs-code-extension" >}})
+- [kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
+- [Radius initialized with `rad init`]({{< ref howto-environment >}})
+
+## Step 1: Create a personal access token
+
+Create a personal access token, this can be from [GitHub](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#about-personal-access-tokens), [GitLab](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html), [Azure DevOps](https://learn.microsoft.com/en-us/azure/devops/organizations/accounts/use-personal-access-tokens-to-authenticate?view=azure-devops&tabs=Windows), or any other Git platform.
+
+The PAT should have access to read the files inside the specific private repository.
+
+## Step 2: Define a secret store resource
+
+Configure a [Radius Secret Store]({{< ref "/guides/author-apps/secrets/overview" >}}) with the personal access token or username + password you previously created, which has access to your private git repository. Define the namespace for the cluster that will contain your [Kubernetes Secret](https://kubernetes.io/docs/concepts/configuration/secret/) with the `resource` property. 
+
+> While this example shows a Radius-managed secret store where Radius creates the underlying secrets infrastructure, you can also bring your own existing secrets. Refer to the [secrets documentation]({{< ref "/guides/author-apps/secrets/overview" >}}) for more information.
+
+Create a Bicep file `env.bicep`, import Radius, and  define your resource:
+
+{{< rad file="snippets/env.bicep" embed=true marker="//SECRETSTORE" >}}
+
+> The property `pat` is required and refers to your personal access token or password, while `username` is optional and refers to a username, if your git platform requires one.
+
+## Step 3: Configure Terraform Recipe git authentication
+
+`recipeConfig` allows you to configure how Recipes should be setup and run. One available option is to specify git credentials for pulling Terraform Recipes from git sources. For more information refer to the [Radius Environment schema]({{< ref environment-schema >}}) page.
+
+In your `env.bicep` file add an Environment resource, along with Recipe configuration which leverages the previously defined secret store for git authentication.
+
+{{< rad file="snippets/env.bicep" embed=true marker="//ENV" >}}
+
+## Step 4: Add a Terraform Recipe
+
+Update your Environment with a Terraform Recipe, pointing to your private git repository. Note that your `templatePath` should contain a `git::` prefix, per the [Terraform module documentation](https://developer.hashicorp.com/terraform/language/modules/sources#generic-git-repository).
+
+{{< rad file="snippets/env-complete.bicep" embed=true marker="//ENV" markdownConfig="{linenos=table,hl_lines=[\"22-30\"],linenostart=30,lineNos=false}" >}}
+
+## Step 5: Deploy your Radius Environment
+
+Deploy your new Radius Environment:
+
+```
+rad deploy ./env.bicep -p pat=******
+```
+
+## Done
+
+Your Radius Environment is now ready to utilize your Radius Recipes stored inside your private registry. For more information on Radius Recipes visit the [Recipes overview page]({{< ref "/guides/recipes/overview" >}}).
+
+## Cleanup
+
+You can delete a Radius Environment by running the following command:
+
+```
+rad env delete my-env
+```
+
+## Further reading
+
+- [Recipes overview]({{< ref "/guides/recipes/overview" >}})
+- [Radius Environments]({{< ref "/guides/deploy-apps/environments/overview" >}})
+- [`rad recipe CLI reference`]({{< ref rad_recipe >}})
+- [`rad env CLI reference`]({{< ref rad_env >}})
diff --git a/docs/content/guides/recipes/howto-private-registry/snippets/env-complete.bicep b/docs/content/guides/recipes/howto-private-registry/snippets/env-complete.bicep
@@ -0,0 +1,55 @@
+//SECRETSTORE
+import radius as radius
+
+@description('Required value, refers to the personal access token or password of the git platform')
+@secure()
+param pat string
+
+resource secretStoreGit 'Applications.Core/secretStores@2023-10-01-preview' = {
+  name: 'my-git-secret-store'
+  properties: {
+    resource: 'my-secret-namespace/github'
+    type: 'generic'
+    data: {
+      pat: {
+        value: pat 
+      }
+    }
+  }
+}
+//SECRETSTORE
+
+//ENV
+resource env 'Applications.Core/environments@2023-10-01-preview' = {
+  name: 'my-env'
+  properties: {
+    compute: {
+      kind: 'kubernetes'
+      namespace: 'my-namespace'
+    }
+    recipeConfig: {
+      terraform: {
+        authentication: {
+          git: {
+            pat: {
+              // The hostname of your git platform, such as 'dev.azure.com' or 'github.com'
+              'github.com':{
+                secret: secretStoreGit.id
+              }
+            }
+          }
+        }
+      }
+    }
+    recipes: {
+      'Applications.Datastores/redisCaches': {
+        default: {
+          templateKind: 'terraform'
+          // Git template path
+          templatePath:'git::https://github.com/my-org/my-repo'
+        }
+      }
+    }
+  }
+}
+//ENV
diff --git a/docs/content/guides/recipes/howto-private-registry/snippets/env.bicep b/docs/content/guides/recipes/howto-private-registry/snippets/env.bicep
@@ -0,0 +1,46 @@
+//SECRETSTORE
+import radius as radius
+
+@description('Required value, refers to the personal access token or password of the git platform')
+@secure()
+param pat string
+
+resource secretStoreGit 'Applications.Core/secretStores@2023-10-01-preview' = {
+  name: 'my-git-secret-store'
+  properties: {
+    resource: 'my-secret-namespace/github'
+    type: 'generic'
+    data: {
+      pat: {
+        value: pat 
+      }
+    }
+  }
+}
+//SECRETSTORE
+
+//ENV
+resource env 'Applications.Core/environments@2023-10-01-preview' = {
+  name: 'my-env'
+  properties: {
+    compute: {
+      kind: 'kubernetes'
+      namespace: 'my-namespace'
+    }
+    recipeConfig: {
+      terraform: {
+        authentication: {
+          git: {
+            pat: {
+              // The hostname of your git platform, such as 'dev.azure.com' or 'github.com'
+              'github.com':{
+                secret: secretStoreGit.id
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
+//ENV
diff --git a/docs/content/reference/limitations.md b/docs/content/reference/limitations.md
@@ -93,6 +93,10 @@ output values object = {
 }
 ```
 
+### Terraform private registries
+
+Currently users cannot run `rad recipe show` on Radius Recipes registered inside of private git registries and will experience an error in the CLI.
+
 ## Bicep & Deployment Engine
 
 ### Currently using a forked version of Bicep