Configuring a deployable architecture

After you add a deployable architecture to your project, you can edit the input values to configure the architecture for deployment.

Configurations can be generic, but many projects use a configuration, or a group of configurations, to deploy resources to different environments. For example, a group of configurations can be used to deploy resources to development, test, and production environments and set up common services outside of the environments. When you deploy your configuration, IBM Cloud® Schematics uses Terraform to apply the underlying plan.

Before you can deploy your project, the inputs, plan, compliance, and estimated cost for the deployable architecture must be validated. Any changes that are made to the configuration are validated to ensure that there aren't any issues or failures.

Setting input values

Input values are used to configure a deployable architecture to match your specific needs. The required inputs vary based on the deployable architecture that you choose. Depending on how the architecture was designed, some inputs might include a set of options that you can select, or you can enter values in fields as text strings.

Referencing values

Configurations can be linked together by using the outputs of one configuration as the inputs in another. For example, a configuration for an application could use an output from an infrastructure configuration, such as a cluster ID, to deploy onto that infrastructure. To achieve this, you can add a reference to an input or an output from another configuration. You can also reference parameters from an environment. When you add a reference, the value is pulled from the input, output, or environment and used as the input value in the architecture that you're configuring.

In the console, you can add a reference in an architecture that you're configuring by hovering over an input and selecting the Reference icon Reference icon .

If you are using the API or CLI to configure a deployable architecture, or if you are editing a deployable architecture stack definition and you want to include a reference, you can write one as a text string. References comply with the URL specification, but use a different ref protocol instead of http. Just like URLs on websites, you can write a reference that's relative to your current context. For example, if you're adding a reference to an input within the configuration that you're currently editing, then your current path is /configs/<configname> and you can write a reference relative to that path. For example, ref:./inputs/region adds a reference to the input that is named region within the same configuration. In this case, the configuration that you're editing does not need to be deployed to reference another value within it.

You can find the name of an output to reference by opening a deployed configuration in your project and going to the Outputs tab.

Referencing values from a configuration

The general format to reference a value in a configuration is as follows:

ref:/configs/<config_name>/inputs_or_outputs/<input_or_output_name>.

You can reference an input or an output from a configuration that was deployed from your project. For example, the following reference points to an output that is named cluster_id within the ProdCluster configuration: ref:/configs/ProdCluster/outputs/cluster_id.

You can add a relative reference to another input within the configuration that you're currently editing. The configuration does not need to be deployed to do so.

Referencing values in a stack

Experimental

If your configuration is part of a stacked deployable architecture, you can reference outputs from other member configurations in the stack and specify inputs for the stack itself. The general format to reference a value for a stack is as follows:

ref:/configs/<stack_name>/members/<member_name>/inputs_or_outputs/<input_or_output_name>

If you want to make a relative reference, you can do so. A relative reference between configurations that are members of the same stack would be formatted as ref:../<member_name>/inputs_or_outputs/<input_or_output_name>. But, if you are referencing a value at the stack level, it would be formatted as ref:../../inputs/<input_name> within the member configuration. Currently, members can't reference outputs from the stack level.

Referencing inputs from an environment

Since environments are created within a project, and not within a configuration, you don't need to include /configs/<configname> if you want to reference a parameter in an environment. But you must include the name of the environment after the environments reference type. Then, specify inputs and provide the name of the input that you want to reference: ref:./environments/<environment_name>/inputs/<name>. You can't add a reference to an authentication parameter or a compliance profile from an environment.

For example, the following reference points to an input parameter that is named cluster_id within the Production environment: ref:./environments/Production/inputs/cluster_id.

Configuring an architecture by using the console

To create a customized configuration, complete the following steps:

From the Security panel, select the authentication method that you want to use to deploy your architecture.

Add an API key by using IBM Cloud® Secrets Manager. This authorizes the project to deploy to a target account and is required to deploy your architecture. For more information, see Using an API key with Secrets Manager to authorize a project to deploy an architecture.
During validation, a Code Risk Analyzer scan is run on your architecture. Select the controls that you want to use during validation. You can use the Architecture default controls, or the Select from Security and Compliance Center option if you have an attachment set up in your target account.

If you select Architecture default:
- The scan uses the default controls that the owner of the deployable architecture added when they onboarded it.
- Controls that the architecture owner added that are also included in the supported set of Security and Compliance Center rules are checked.
- Any extra controls that the architecture owner added that are not included in the list of supported rules are not checked when you validate your configuration.
- If the owner of the deployable architecture didn't add compliance controls to their product, the full set of Security and Compliance Center rules is used.
To view the list of added controls, go to the IBM Cloud® catalog and select the deployable architecture that you're configuring. The Security & compliance tab lists all of the controls that were added to the deployable architecture.

If you select Select from Security and Compliance Center, you must have an instance of the service and an attachment through Security and Compliance Center in the target account that you want to deploy to. For help with creating an attachment, see Evaluating resource configuration with IBM Cloud Security and Compliance Center.
From the Required panel, enter values for the required inputs for the deployable architecture configuration.
Optional: You can add values by going to the Optional panel.
Click Save.
Click Validate. The modal that is displayed provides more details about your in-progress validation.

If the validation fails, you can troubleshoot the failure. Or, an administrator on the IBM Cloud Projects service can review the results through the Schematics service and override the failure and approve the configuration to deploy anyway. However, ensure that the pipeline failed due to the Code Risk Analyzer scan and not because of a validation or plan failure. It is not recommended to override a failure that is flagged due to a validation or plan failure as the configuration might not deploy successfully. For more information about security and compliance in projects, see Achieving continuous compliance as an enterprise.

If you're configuring a deployable architecture stack, make sure to validate each architecture in the stack according to their dependencies.

Approving configuration changes by using the console

After you validate your configuration, the changes must be approved by an editor or administrator on the IBM Cloud Projects service. Complete the following steps to approve changes:

From the projects list, select a project.
Check that there aren't any outstanding needs attention items on the Overview tab in your project. Needs attention items can block your ability to deploy.
Go to the Configurations tab, and select a deployable architecture configuration.
Click Edit.
Click View last validation.
Add a comment providing more details about the approval, and click Approve.

If your validation failed due to the Code Risk Analyzer scan, an administrator on the IBM Cloud Projects service can override the failure and approve the configuration to deploy anyway.

Configuring an architecture by using the CLI

To add a configuration to a project by using the CLI, run the following ibmcloud project config-create command:

ibmcloud project config-create --project-id PROJECT-ID [--definition DEFINITION] [--schematics SCHEMATICS]

For more information about the command parameters, see ibmcloud project config-create.

Approving configuration changes by using the CLI

Run the following ibmcloud project config-validate command to get a validation check on your configuration:
```
ibmcloud project config-validate --project-id PROJECT-ID --id ID
```
For more information about the command parameters, see ibmcloud project config-validate.
After validating your configuration, approve your configuration edits and merge them to the main configuration by running the following ibmcloud project config-approve command:
```
ibmcloud project config-approve --project-id PROJECT-ID --id ID [--comment COMMENT]
```
For more information about the command parameters, see ibmcloud project config-approve.