From 3aff56e772dba0008780a94e84961026edf6a85a Mon Sep 17 00:00:00 2001 From: rad-ci-bot <103787451+rad-ci-bot@users.noreply.github.com> Date: Fri, 1 Mar 2024 10:59:46 -0800 Subject: [PATCH 1/3] Update auto-generated documentation (#1075) * Autogenerate reference docs Signed-off-by: rad-ci-bot * Spelling Signed-off-by: Aaron Crawfis --------- Signed-off-by: rad-ci-bot Signed-off-by: Aaron Crawfis Co-authored-by: rad-ci-bot Co-authored-by: Aaron Crawfis --- .github/config/en-custom.txt | 3 ++ .../2023-10-01-preview/environments/index.md | 42 ++++++++++++++++--- 2 files changed, 40 insertions(+), 5 deletions(-) diff --git a/.github/config/en-custom.txt b/.github/config/en-custom.txt index d3cf05d47..676a04f90 100644 --- a/.github/config/en-custom.txt +++ b/.github/config/en-custom.txt @@ -1234,3 +1234,6 @@ GitAuthConfig GitAuthConfigPat SecretConfig appgraph +EnvironmentVariables +TerraformConfigPropertiesProviders +ProviderConfigProperties diff --git a/docs/content/reference/resources/applications/applications.core/2023-10-01-preview/environments/index.md b/docs/content/reference/resources/applications/applications.core/2023-10-01-preview/environments/index.md index e78a47f51..0c817e3e4 100644 --- a/docs/content/reference/resources/applications/applications.core/2023-10-01-preview/environments/index.md +++ b/docs/content/reference/resources/applications/applications.core/2023-10-01-preview/environments/index.md @@ -32,7 +32,7 @@ description: "Detailed reference documentation for applications.core/environment |----------|------|-------------| | **compute** | [EnvironmentCompute](#environmentcompute) | Represents backing compute resource
_(required)_ | | **extensions** | [Extension](#extension)[] | The environment extension. | -| **providers** | [Providers](#providers) | The Cloud providers configuration | +| **providers** | [Providers](#providers) | The Cloud providers configuration. | | **provisioningState** | 'Accepted' | 'Canceled' | 'Deleting' | 'Failed' | 'Provisioning' | 'Succeeded' | 'Updating' | Provisioning state of the resource at the time the operation was called
_(read-only)_ | | **recipeConfig** | [RecipeConfigProperties](#recipeconfigproperties) | Configuration for Recipes. Defines how each type of Recipe should be configured and run. | | **recipes** | [EnvironmentPropertiesRecipes](#environmentpropertiesrecipes) | Specifies Recipes linked to the Environment. | @@ -145,8 +145,8 @@ description: "Detailed reference documentation for applications.core/environment | Property | Type | Description | |----------|------|-------------| -| **aws** | [ProvidersAws](#providersaws) | The AWS cloud provider definition | -| **azure** | [ProvidersAzure](#providersazure) | The Azure cloud provider definition | +| **aws** | [ProvidersAws](#providersaws) | The AWS cloud provider definition. | +| **azure** | [ProvidersAzure](#providersazure) | The Azure cloud provider definition. | ### ProvidersAws @@ -154,7 +154,7 @@ description: "Detailed reference documentation for applications.core/environment | Property | Type | Description | |----------|------|-------------| -| **scope** | string | Target scope for AWS resources to be deployed into. For example: '/planes/aws/aws/accounts/000000000000/regions/us-west-2'
_(required)_ | +| **scope** | string | Target scope for AWS resources to be deployed into. For example: '/planes/aws/aws/accounts/000000000000/regions/us-west-2'.
_(required)_ | ### ProvidersAzure @@ -162,7 +162,7 @@ description: "Detailed reference documentation for applications.core/environment | Property | Type | Description | |----------|------|-------------| -| **scope** | string | Target scope for Azure resources to be deployed into. For example: '/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/testGroup'
_(required)_ | +| **scope** | string | Target scope for Azure resources to be deployed into. For example: '/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/testGroup'.
_(required)_ | ### RecipeConfigProperties @@ -170,8 +170,19 @@ description: "Detailed reference documentation for applications.core/environment | Property | Type | Description | |----------|------|-------------| +| **env** | [EnvironmentVariables](#environmentvariables) | The environment variables injected during Terraform Recipe execution for the recipes in the environment. | | **terraform** | [TerraformConfigProperties](#terraformconfigproperties) | Configuration for Terraform Recipes. Controls how Terraform plans and applies templates as part of Recipe deployment. | +### EnvironmentVariables + +#### Properties + +* **none** + +#### Additional Properties + +* **Additional Properties Type**: string + ### TerraformConfigProperties #### Properties @@ -179,6 +190,7 @@ description: "Detailed reference documentation for applications.core/environment | Property | Type | Description | |----------|------|-------------| | **authentication** | [AuthConfig](#authconfig) | Authentication information used to access private Terraform module sources. Supported module sources: Git. | +| **providers** | [TerraformConfigPropertiesProviders](#terraformconfigpropertiesproviders) | Configuration for Terraform Recipe Providers. Controls how Terraform interacts with cloud providers, SaaS providers, and other APIs. For more information, please see: https://developer.hashicorp.com/terraform/language/providers/configuration. | ### AuthConfig @@ -214,6 +226,26 @@ description: "Detailed reference documentation for applications.core/environment |----------|------|-------------| | **secret** | string | The ID of an Applications.Core/SecretStore resource containing the Git platform personal access token (PAT). The secret store must have a secret named 'pat', containing the PAT value. A secret named 'username' is optional, containing the username associated with the pat. By default no username is specified. | +### TerraformConfigPropertiesProviders + +#### Properties + +* **none** + +#### Additional Properties + +* **Additional Properties Type**: [ProviderConfigProperties](#providerconfigproperties)[] + +### ProviderConfigProperties + +#### Properties + +* **none** + +#### Additional Properties + +* **Additional Properties Type**: any + ### EnvironmentPropertiesRecipes #### Properties From 35e625798e2b96994ac5521fb94b34938179e674 Mon Sep 17 00:00:00 2001 From: rad-ci-bot <103787451+rad-ci-bot@users.noreply.github.com> Date: Mon, 4 Mar 2024 16:34:45 -0800 Subject: [PATCH 2/3] Update auto-generated documentation (#1080) * Autogenerate reference docs Signed-off-by: rad-ci-bot * Fix command link Signed-off-by: Aaron Crawfis --------- Signed-off-by: rad-ci-bot Signed-off-by: Aaron Crawfis Co-authored-by: rad-ci-bot Co-authored-by: Aaron Crawfis --- docs/content/reference/cli/rad_application.md | 2 +- ...onnections.md => rad_application_graph.md} | 28 +++++++++---------- docs/content/tutorials/new-app/index.md | 4 +-- 3 files changed, 17 insertions(+), 17 deletions(-) rename docs/content/reference/cli/{rad_application_connections.md => rad_application_graph.md} (50%) diff --git a/docs/content/reference/cli/rad_application.md b/docs/content/reference/cli/rad_application.md index e1b0fc9cc..d36e417fc 100644 --- a/docs/content/reference/cli/rad_application.md +++ b/docs/content/reference/cli/rad_application.md @@ -30,8 +30,8 @@ Manage Radius Applications ### SEE ALSO * [rad]({{< ref rad.md >}}) - Radius CLI -* [rad application connections]({{< ref rad_application_connections.md >}}) - Shows the connections for an application. * [rad application delete]({{< ref rad_application_delete.md >}}) - Delete Radius Application +* [rad application graph]({{< ref rad_application_graph.md >}}) - Shows the application graph for an application. * [rad application list]({{< ref rad_application_list.md >}}) - List Radius Applications * [rad application show]({{< ref rad_application_show.md >}}) - Show Radius Application details * [rad application status]({{< ref rad_application_status.md >}}) - Show Radius Application status diff --git a/docs/content/reference/cli/rad_application_connections.md b/docs/content/reference/cli/rad_application_graph.md similarity index 50% rename from docs/content/reference/cli/rad_application_connections.md rename to docs/content/reference/cli/rad_application_graph.md index 8c1c81811..da4e1cbe5 100644 --- a/docs/content/reference/cli/rad_application_connections.md +++ b/docs/content/reference/cli/rad_application_graph.md @@ -1,32 +1,32 @@ --- type: docs -title: "rad application connections CLI reference" -linkTitle: "rad application connections" -slug: rad_application_connections -url: /reference/cli/rad_application_connections/ -description: "Details on the rad application connections Radius CLI command" +title: "rad application graph CLI reference" +linkTitle: "rad application graph" +slug: rad_application_graph +url: /reference/cli/rad_application_graph/ +description: "Details on the rad application graph Radius CLI command" --- -## rad application connections +## rad application graph -Shows the connections for an application. +Shows the application graph for an application. ### Synopsis -Shows the connections for an application +Shows the application graph for an application. ``` -rad application connections [flags] +rad application graph [flags] ``` ### Examples ``` -# Show connections for current application -rad app connections +# Show graph for current application +rad app graph -# Show connections for specified application -rad app connections my-application +# Show graph for specified application +rad app graph my-application ``` ### Options @@ -35,7 +35,7 @@ rad app connections my-application -a, --application string The application name -e, --environment string The environment name -g, --group string The resource group name - -h, --help help for connections + -h, --help help for graph -w, --workspace string The workspace name ``` diff --git a/docs/content/tutorials/new-app/index.md b/docs/content/tutorials/new-app/index.md index ef4103987..c5f26c471 100644 --- a/docs/content/tutorials/new-app/index.md +++ b/docs/content/tutorials/new-app/index.md @@ -88,10 +88,10 @@ Radius Applications are where all your app's resources and relationships come to - **`environment`** specifies the Radius Environment which the Applications "binds" to at deployment. This is what determines where containers should run (_Kubernetes_) and which namespace to deploy into (_prefixed with "default"_). In this case, the application will be deployed into the `default` Environment that was created by `rad init`. - **`compute`** specifies the hosting platform where running services in the Application will run. In this case, the services will be deployed into the `default-myapp` Kubernetes namespace within the same cluster where Radius is installed. -1. Let's take a look inside the Application to see what's deployed. Run [`rad app connections`]({{< ref rad_application_connections >}}) to print the Application's resources and relationships: +1. Let's take a look inside the Application to see what's deployed. Run [`rad app graph`]({{< ref rad_application_graph >}}) to print the Application's resources and relationships: ```bash - rad app connections + rad app graph ``` You'll see that nothing has been deployed yet and the app is empty: From 84f0979492a81dfe8bb4858bbaf83be3b9f656b6 Mon Sep 17 00:00:00 2001 From: jasonviviano <83607984+jasonviviano@users.noreply.github.com> Date: Mon, 11 Mar 2024 15:09:09 -0400 Subject: [PATCH 3/3] 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 <83607984+jasonviviano@users.noreply.github.com> * Addressed feedback with Vishwanath's help. Signed-off-by: jasonviviano <83607984+jasonviviano@users.noreply.github.com> * Fixed snippet Signed-off-by: jasonviviano <83607984+jasonviviano@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Will <28876888+willtsai@users.noreply.github.com> Signed-off-by: jasonviviano <83607984+jasonviviano@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Aaron Crawfis Signed-off-by: jasonviviano <83607984+jasonviviano@users.noreply.github.com> * Addressed feedback on howto-private-registry Signed-off-by: jasonviviano <83607984+jasonviviano@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Aaron Crawfis Signed-off-by: jasonviviano <83607984+jasonviviano@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Vishwanath Hiremath <100623239+vishwahiremat@users.noreply.github.com> Signed-off-by: jasonviviano <83607984+jasonviviano@users.noreply.github.com> * Addressed certain changes to the steps of the guide. Signed-off-by: jasonviviano <83607984+jasonviviano@users.noreply.github.com> * Fixed naming. Signed-off-by: jasonviviano <83607984+jasonviviano@users.noreply.github.com> * Addressed feedback Signed-off-by: jasonviviano <83607984+jasonviviano@users.noreply.github.com> * Spellcheck fix Signed-off-by: jasonviviano <83607984+jasonviviano@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Aaron Crawfis Signed-off-by: jasonviviano <83607984+jasonviviano@users.noreply.github.com> * Apply suggestions from code review Signed-off-by: jasonviviano <83607984+jasonviviano@users.noreply.github.com> * Fixed snippet render Signed-off-by: jasonviviano <83607984+jasonviviano@users.noreply.github.com> * Moved folder Signed-off-by: jasonviviano <83607984+jasonviviano@users.noreply.github.com> * Added a note linking to the limitations page Signed-off-by: jasonviviano <83607984+jasonviviano@users.noreply.github.com> * Added an explanation to the `resource` property. Signed-off-by: jasonviviano <83607984+jasonviviano@users.noreply.github.com> * Fixed spelling Signed-off-by: jasonviviano <83607984+jasonviviano@users.noreply.github.com> * Apply suggestions from code review Co-authored-by: Aaron Crawfis Signed-off-by: jasonviviano <83607984+jasonviviano@users.noreply.github.com> * Addressed feedback on how-to guide Signed-off-by: jasonviviano <83607984+jasonviviano@users.noreply.github.com> * Spellcheck fix Signed-off-by: jasonviviano <83607984+jasonviviano@users.noreply.github.com> --------- Signed-off-by: jasonviviano <83607984+jasonviviano@users.noreply.github.com> Co-authored-by: Will <28876888+willtsai@users.noreply.github.com> Co-authored-by: Aaron Crawfis Co-authored-by: Vishwanath Hiremath <100623239+vishwahiremat@users.noreply.github.com> --- .github/config/en-custom.txt | 3 + .../recipes/howto-private-registry/index.md | 81 +++++++++++++++++++ .../snippets/env-complete.bicep | 55 +++++++++++++ .../howto-private-registry/snippets/env.bicep | 46 +++++++++++ docs/content/reference/limitations.md | 4 + 5 files changed, 189 insertions(+) create mode 100644 docs/content/guides/recipes/howto-private-registry/index.md create mode 100644 docs/content/guides/recipes/howto-private-registry/snippets/env-complete.bicep create mode 100644 docs/content/guides/recipes/howto-private-registry/snippets/env.bicep diff --git a/.github/config/en-custom.txt b/.github/config/en-custom.txt index 676a04f90..399d1de04 100644 --- 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 new file mode 100644 index 000000000..d121d9d0f --- /dev/null +++ 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 >}}) \ No newline at end of file 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 new file mode 100644 index 000000000..49f7822a0 --- /dev/null +++ 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 new file mode 100644 index 000000000..78fa42ebe --- /dev/null +++ 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 index 9f470d7bc..760f63aeb 100644 --- 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