chore(pulumi): make pulumi backendURL and orgName as non-required fie…

…lds (#4164)

Co-authored-by: Anna Mager <[email protected]>

docs/pulumi-plugin/configure-modules.md

@@ -24,4 +24,39 @@ pulumiVariables:
 # order (and take precedence over variables defined in this module's pulumiVariables).
 pulumiVarfiles: [my-default-varfile.yaml, dev.yaml]
 ```
+
+In case you want to use different backends for different Garden environments and you want to use module specific pulumi managed state backend
+organizations, you can configure your modules as follows. This example uses two different pulumi backends. For the `prod` environment it uses
+the pulumi managed state backend and for the `dev` environment it uses a self managed S3 backend.
+
+Note that when you use a self managed state backend `cacheStatus` needs to be set to `false`, since caching is only available with the
+pulumi managed state backend. The same applies to `orgName` which only makes sense in the context of the pulumi managed state backend.
+Please ensure that `orgName` is set to `null` or empty string `""` for all the environments that are not using the pulumi managed state backend.
+
+```yaml
+kind: Project
+name: pulumi
+defaultEnvironment: dev
+environments:
+  - name: dev
+    variables:
+      backendURL: s3://<bucket-name>
+  - name: prod
+providers:
+  - name: pulumi
+    environments: [dev, prod]
+    backendURL: ${var.backendURL || null} # backendURL defaults to the pulumi managed state backend if null or empty string ""
+---
+kind: Module
+type: pulumi
+name: s3stack
+stack: s3
+orgName: '${environment.name == "prod" ? "s3stack-prod" : ""}' # orgName has to be null or an empty string "" for self-managed state backends
+createStack: true
+cacheStatus: '${environment.name == "prod" ? true : false}' # cacheStatus has to be set to false for self-managed state backends
+description: Creates an s3 bucket
+pulumiVariables:
+  environment: ${environment.name}
+```
+
 See the [reference docs for the pulumi module type](../reference/module-types/pulumi.md) for more info on each available config field (and how/when to use them).

docs/pulumi-plugin/configure-provider.md

@@ -13,4 +13,47 @@ providers:
   - name: pulumi # <----
   ...
 ```
+
+In case you want to use different backends for different Garden environments you can configure your provider and modules follows. This example uses two
+different pulumi backends. In the `dev` environment it uses a self-managed state backend, in this case an S3 bucket which is specified
+with the `backendURL`.
+In the `prod` environment it uses pulumi managed state backend, which is the default so we don't need to specify a `backendURL`. 
+
+Note that when you use a self managed state backend, Garden's module level `cacheStatus` needs to be set to `false`, since 
+caching is only available with the pulumi managed state backend. The same applies to `orgName` which only makes sense in the context of the pulumi managed state backend.
+Please ensure that `orgName` is set to `null` or empty string `""` for all the environments that are not using the pulumi managed state backend.
+
+```yaml
+---
+kind: Project
+name: pulumi
+defaultEnvironment: dev
+variables:
+  cacheStatus: true
+environments:
+  - name: dev
+    variables:
+      backendURL: s3://<bucket-name>
+      cacheStatus: false # cacheStatus has to be set to false for self-managed state backends
+  - name: prod
+    variables:
+      orgName: garden
+providers:
+  - name: pulumi
+    environments: [dev, prod]
+    orgName: ${var.orgName || null} # ensure orgName is null or "" for self-managed state backends
+    backendURL: ${var.backendURL || null} # defaults to Pulumi managed state backend if null or ""
+
+---
+kind: Module
+type: pulumi
+name: aws-s3
+stack: ${environment.name}
+createStack: true
+cacheStatus: ${var.cacheStatus} # cacheStatus has to be set to false for self-managed state backends
+description: Creates an s3 bucket
+pulumiVariables:
+  environment: ${environment.name}
+```
+
 There are several configuration options you can set on the provider—see the [reference docs for the pulumi provider](../reference/providers/pulumi.md) for details.

docs/reference/action-types/Deploy/pulumi.md

@@ -227,11 +227,6 @@ spec:
   # To use the default org, set to null.
   orgName:
 
-  # The name of the Pulumi backend URL to use. Overrides the `backendURL` set on the pulumi provider (if any).
-  # Set this option as per list of available self-managed state backends on
-  # https://www.pulumi.com/docs/intro/concepts/state/#using-a-self-managed-backend
-  backendURL:
-
   # When set to true, the pulumi stack will be tagged with the Garden service version when deploying. The tag
   # will then be used for service status checks for this service. If the version doesn't change between deploys,
   # the subsequent deploy is skipped.
@@ -676,18 +671,6 @@ To use the default org, set to null.
 | -------- | -------- |
 | `string` | No       |
 
-### `spec.backendURL`
-
-[spec](#spec) > backendURL
-
-The name of the Pulumi backend URL to use. Overrides the `backendURL` set on the pulumi provider (if any).
-Set this option as per list of available self-managed state backends on
-https://www.pulumi.com/docs/intro/concepts/state/#using-a-self-managed-backend
-
-| Type     | Required |
-| -------- | -------- |
-| `string` | No       |
-
 ### `spec.cacheStatus`
 
 [spec](#spec) > cacheStatus

docs/reference/module-types/pulumi.md

@@ -208,11 +208,6 @@ pulumiVarfiles: []
 # To use the default org, set to null.
 orgName:
 
-# The name of the Pulumi backend URL to use. Overrides the `backendURL` set on the pulumi provider (if any).
-# Set this option as per list of available self-managed state backends on
-# https://www.pulumi.com/docs/intro/concepts/state/#using-a-self-managed-backend
-backendURL:
-
 # When set to true, the pulumi stack will be tagged with the Garden service version when deploying. The tag
 # will then be used for service status checks for this service. If the version doesn't change between deploys,
 # the subsequent deploy is skipped.
@@ -626,16 +621,6 @@ To use the default org, set to null.
 | -------- | -------- |
 | `string` | No       |
 
-### `backendURL`
-
-The name of the Pulumi backend URL to use. Overrides the `backendURL` set on the pulumi provider (if any).
-Set this option as per list of available self-managed state backends on
-https://www.pulumi.com/docs/intro/concepts/state/#using-a-self-managed-backend
-
-| Type     | Required |
-| -------- | -------- |
-| `string` | No       |
-
 ### `cacheStatus`
 
 When set to true, the pulumi stack will be tagged with the Garden service version when deploying. The tag

docs/reference/providers/pulumi.md

@@ -43,7 +43,8 @@ providers:
     previewDir:
 
     # The name of the pulumi organization to use. This option can also be set on the module level, in which case it
-    # overrides this provider-level option.
+    # overrides this provider-level option. Note that setting the organization name is only necessary when using
+    # pulumi managed backend with an organization.
     orgName:
 
     # The URL of the state backend endpoint used. This option can also be set on the module level, in which case it
@@ -149,7 +150,8 @@ This option can be useful when you want to provide a folder of pre-approved pulu
 [providers](#providers) > orgName
 
 The name of the pulumi organization to use. This option can also be set on the module level, in which case it
-overrides this provider-level option.
+overrides this provider-level option. Note that setting the organization name is only necessary when using
+pulumi managed backend with an organization.
 
 | Type     | Required |
 | -------- | -------- |
@@ -165,7 +167,7 @@ https://www.pulumi.com/docs/intro/concepts/state/#using-a-self-managed-backend
 
 | Type     | Default                    | Required |
 | -------- | -------------------------- | -------- |
-| `string` | `"https://api.pulumi.com"` | Yes      |
+| `string` | `"https://api.pulumi.com"` | No       |
 
 ### `providers[].pluginTaskConcurrencyLimit`
 

plugins/pulumi/config.ts

@@ -48,11 +48,12 @@ export const pulumiProviderConfigSchema = providerConfigBaseSchema()
         This option can be useful when you want to provide a folder of pre-approved pulumi plans to a CI pipeline step.
     `
       ),
-    orgName: joi.string().description(dedent`
+    orgName: joi.string().optional().empty(["", null]).description(dedent`
       The name of the pulumi organization to use. This option can also be set on the module level, in which case it
-      overrides this provider-level option.
+      overrides this provider-level option. Note that setting the organization name is only necessary when using
+      pulumi managed backend with an organization.
     `),
-    backendURL: joi.string().uri().default("https://api.pulumi.com").required().description(dedent`
+    backendURL: joi.string().optional().uri().empty(["", null]).default("https://api.pulumi.com").description(dedent`
       The URL of the state backend endpoint used. This option can also be set on the module level, in which case it
       overrides this  provider-level option. Set this option as per list of available self-managed state backends on
       https://www.pulumi.com/docs/intro/concepts/state/#using-a-self-managed-backend
@@ -72,8 +73,7 @@ export interface PulumiDeploySpec {
   createStack: boolean
   pulumiVariables: DeepPrimitiveMap
   pulumiVarfiles: string[]
-  orgName?: string | null
-  backendURL?: string | null
+  orgName?: string
   cacheStatus: boolean
   stackReferences: string[]
   deployFromPreview: boolean
@@ -138,15 +138,10 @@ export const pulumiDeploySpecSchema = () =>
           config. Simply specify all the config variables at the top level.
         `
     ),
-    orgName: joi.string().optional().allow(null).description(dedent`
+    orgName: joi.string().optional().empty(["", null]).description(dedent`
       The name of the pulumi organization to use. Overrides the \`orgName\` set on the pulumi provider (if any).
       To use the default org, set to null.
     `),
-    backendURL: joi.string().uri().optional().allow(null).description(dedent`
-      The name of the Pulumi backend URL to use. Overrides the \`backendURL\` set on the pulumi provider (if any).
-      Set this option as per list of available self-managed state backends on
-      https://www.pulumi.com/docs/intro/concepts/state/#using-a-self-managed-backend
-    `),
     cacheStatus: joi
       .boolean()
       .default(false)

plugins/pulumi/handlers.ts

@@ -53,7 +53,7 @@ export const configurePulumiModule: ModuleActionHandlers["configure"] = async ({
 
   const provider = ctx.provider as PulumiProvider
 
-  const backendUrl = moduleConfig.spec.backendURL || provider.config.backendURL
+  const backendUrl = provider.config.backendURL
   const orgName = moduleConfig.spec.orgName || provider.config.orgName
 
   // Check to avoid using `orgName` or `cacheStatus: true` with non-pulumi managed backends

plugins/pulumi/helpers.ts

@@ -269,8 +269,7 @@ export async function applyConfig(params: PulumiParams & { previewDirPath?: stri
   log.debug(`merged vars: ${JSON.stringify(vars, null, 2)}`)
   stackConfig.config = vars
 
-  const backendUrl = getBackendUrl(params.provider, params.action)
-  stackConfig.backend = { url: backendUrl }
+  stackConfig.backend = { url: params.provider.config.backendURL }
 
   if (stackConfigFileExists && isEmpty(vars)) {
     log.debug(deline`
@@ -404,25 +403,15 @@ export async function reimportStack(params: PulumiParams): Promise<void> {
 
 // Lower-level helpers
 
-function getBackendUrl(provider: PulumiProvider, action: PulumiDeploy): string {
-  const backendURL = action.getConfig().spec.backendURL
-  if (backendURL) {
-    return backendURL
-  } else {
-    return provider.config.backendURL
-  }
-}
-
 export function ensureEnv(pulumiParams: PulumiParams): { [key: string]: string } {
-  const backendUrl = getBackendUrl(pulumiParams.provider, pulumiParams.action)
+  const backendUrl = pulumiParams.provider.config.backendURL
   return { PULUMI_BACKEND_URL: backendUrl, ...defaultPulumiEnv }
 }
 
 export async function selectStack({ action, ctx, provider, log }: PulumiParams) {
   const root = getActionStackRoot(action)
   const spec = action.getSpec()
   const stackName = spec.stack || ctx.environmentName
-
   const orgName = getOrgName(<PulumiProvider>ctx.provider, action)
   const qualifiedStackName = orgName ? `${orgName}/${stackName}` : stackName
   const args = ["stack", "select", qualifiedStackName]
@@ -432,12 +421,12 @@ export async function selectStack({ action, ctx, provider, log }: PulumiParams)
   return stackName
 }
 
-function getOrgName(provider: PulumiProvider, action: Resolved<PulumiDeploy>): string | null {
+function getOrgName(provider: PulumiProvider, action: Resolved<PulumiDeploy>): string | undefined {
   const orgName = action.getSpec("orgName")
-  if (orgName || orgName === null) {
+  if (orgName) {
     return orgName
   } else {
-    return provider.config.orgName || null
+    return provider.config.orgName
   }
 }