Configuration reference

Creating an instance from the Red Hat OpenShift web console

To create a configuration object by using the Red Hat OpenShift web console, complete the following steps:

1. Create the type of configuration file that you require; for example, accounts.yaml, generic.zip, or odbc.ini. For information about the supported configuration types and how to create the required configuration file, see Configuration types.
   Tip: You might find it useful to back up this file to a preferred location in case you want to update the configuration at a future date. For example, if you need to update the stored credentials in an accounts.yaml file, you can simply overwrite the outdated account details in the file before running a Base64 encoder as described in Updating an instance from the Red Hat OpenShift web console and Updating an instance from the Red Hat OpenShift CLI or Kubernetes CLI.
2. Run a Base64 encoder against the configuration file and save the generated value.

   
   By default, the Operator will automatically generate a secret to store this Base64-encoded value when the configuration object is created, but you can alternatively choose to manually create a secret to store the contents of the configuration file that you created in the previous step. If you would prefer to create your own secret, you can skip this step.

   Tip: Depending on your operating system, you can use commands such as base64, echo, or certutil to Base64 encode data in a file or string. For example, for configuration types such as BarAuth or S3Credentials, which can be specified as a string in JSON format, you can directly Base64-encocde the JSON content from the command line by running a command on Linux as follows:

   echo -n 'JSONcontent' | base64

   Example:

   echo -n '{"authType":"BASIC_AUTH","credentials":{"username":"joebloggs@email.com","password":"myPassword"}}' | base64

3. From a browser window, log in to the Red Hat OpenShift Container Platform web console. Ensure that you are in the Administrator perspective .
4. Optional. If the type of configuration that you want to create contains sensitive data (secrets), create a secret to securely store the Base64-encoded value. Examples of such configuration types are Accounts, Agentx, and setdbparms.txt. (For information about which configuration types contain secrets, go to Learn more about the configuration types, click the link for a configuration type, and then check the Contains secrets column in the Summary of key details for the configuration type table.)
   Note: Only perform this step if you prefer to manually create and manage your own secret. If you skip this step, a secret is automatically generated by default to store the Base64-encoded value (specified in the Data field in Form view or spec.data in YAML view) when you save the configuration.
   1. From the navigation, click Workloads > Secrets.
   2. If necessary, select the namespace (project) in which you installed the IBM App Connect Operator.
   3. Click Create > Key/Value Secret and then specify a name for the secret in the Secret Name field.
   4. Specify configuration in the Key field.
   5. To complete the Value field, browse or use drag-and-drop to select the configuration file, or directly paste the contents of the configuration file in the field.
   6. Click Create.
   7. Make a note of the secret name so that you can specify it while creating the configuration object.
5. From the navigation, click Operators > Installed Operators.
6. If required, select the namespace (project) in which you installed the IBM App Connect Operator.
7. From the Installed Operators page, click IBM App Connect.
8. From the Operator details page for the App Connect Operator, click the Configuration tab. Any previously created configuration objects are displayed in a table.
9. Click Create Configuration.

   From the Details tab on the Operator details page, you can also locate the Configuration tile and click Create instance to specify custom resource settings for the configuration object.

10. To use the Form view, complete the fields as follows:
    • Name: Specify a unique short name by which the configuration object can be identified.
    • Type: From the drop-down list, select the type of configuration that you want to create. For information about the valid values, see spec.type in the Custom resource values table.
    • Data: Specify the Base64-encoded value that you generated earlier. (When you save, a secret will be automatically generated to store this value.)
      Note: If you manually created a secret to store the contents of the configuration file, leave this field blank, and instead specify that secret in the Secret Name field.
    • Description: Specify a description for the configuration object.
    • Secret Name: If you manually created a secret to store the contents of the configuration file, specify the secret in this field.
      Note: Leave this field blank if you specified a Base64-encoded value in the Data field.
11. Optional: If you prefer to use the YAML view, click YAML view and then update the contents of the YAML editor with the parameters and values that you require for this configuration object.

    
    To view the full set of parameters and values available, see Custom resource values. (This section also describes how the spec.data value is stored after you create the configuration object.)

    The following YAML code shows an example of what your Configuration custom resource settings should look like if you did not manually create a secret to store the contents of the configuration file. Note that the value of the spec.data parameter must be the Base64-encoded file content that you generated in an earlier step. The metadata.name, metadata.namespace, spec.description, and spec.type values represent your preferred values for the type of configuration being created.

    apiVersion: appconnect.ibm.com/v1beta1
    kind: Configuration
    metadata:
      name: acct-googleanalytics
      namespace: mynamespace
    spec:
      data: ThisRepresentsAveryLongBase64encodedDummyVaLue=
      description: Stores account details for Google Analytics
      type: accounts

    The following YAML code shows an example of what your Configuration custom resource settings should look like if you manually created a secret to store the contents of the configuration file (that contains secrets). Note that the value of the spec.secretName parameter must be the name of this secret.

    apiVersion: appconnect.ibm.com/v1beta1
    kind: Configuration
    metadata:
      name: acct-googleanalytics
      namespace: mynamespace
    spec:
      description: Stores account details for Google Analytics
      secretName: scrt-googleanalytics
      type: accounts

12. Click Create. An entry for the configuration object is shown in the Configurations table without a status because the configuration object simply represents a document that is referenced in an integration server, integration runtime, the App Connect Dashboard, or App Connect Designer.
13. Click the configuration object name to view information about its definition.

    You can use the breadcrumb trail to return to the (previous) Operator details page.

What to do next

• If appropriate, you can apply this configuration to an integration server or integration runtime in the same namespace by specifying the metadata.name value of the configuration object in the integration server or integration runtime's spec.configuration setting. For more information, see Integration server reference: Creating an instance from the Red Hat OpenShift web console and Integration runtime reference: Creating an instance from the Red Hat OpenShift web console.

  If created for use with an integration server or integration runtime, you can alternatively apply this configuration to an integration server or integration runtime that you deploy in an App Connect Dashboard instance (that is in the same namespace), as described in Creating an integration server to run your BAR file resources, Creating an integration server to run IBM App Connect Enterprise Toolkit integrations, and Creating an integration runtime to run your BAR file resources.

• If you created a configuration object of type S3Credentials for use with your App Connect Dashboard instance in the same namespace, you can apply this configuration to the Dashboard by specifying the metadata.name value of the configuration object in the Dashboard's spec.storage.s3Configuration setting. For more information, see Dashboard reference: Creating an instance from the Red Hat OpenShift web console.
• If you created a configuration object of type S3Credentials for use with your App Connect Designer instance in the same namespace, you can apply this configuration to the Designer instance by specifying the metadata.name value of the configuration object in the Designer's spec.designerMappingAssist.incrementalLearning.storage.s3Configuration setting. For more information, see Designer reference: Creating an instance from the Red Hat OpenShift web console.

Creating an instance from the Red Hat OpenShift CLI or Kubernetes CLI

To create a configuration object from the Red Hat OpenShift CLI, complete the following steps.

1. Create the type of configuration file that you require; for example, accounts.yaml, generic.zip, or odbc.ini. For information about the supported configuration types and how to create the required configuration file, see Configuration types.
   Tip: You might find it useful to back up this file to a preferred location in case you want to update the configuration at a future date. For example, if you need to update the stored credentials in an accounts.yaml file, you can simply overwrite the outdated account details in the file before running a Base64 encoder as described in Updating an instance from the Red Hat OpenShift web console and Updating an instance from the Red Hat OpenShift CLI or Kubernetes CLI.
2. Run a Base64 encoder against the configuration file and save the generated value.

   
   By default, the Operator will automatically generate a secret to store this Base64-encoded value when the configuration object is created, but you can alternatively choose to manually create a secret to store the contents of the configuration file that you created in the previous step. If you would prefer to create your own secret, you can skip this step.

   Tip: Depending on your operating system, you can use commands such as base64, echo, or certutil to Base64 encode data in a file or string. For example, for configuration types such as BarAuth or S3Credentials, which can be specified as a string in JSON format, you can directly Base64-encocde the JSON content from the command line by running a command on Linux as follows:

   echo -n 'JSONcontent' | base64

   Example:

   echo -n '{"authType":"BASIC_AUTH","credentials":{"username":"joebloggs@email.com","password":"myPassword"}}' | base64

3. Optional. If the type of configuration that you want to create contains sensitive data (secrets), create a secret to securely store the Base64-encoded value. Examples of such configuration types are Accounts, Agentx, and setdbparms.txt. (For information about which configuration types contain secrets, go to Learn more about the configuration types, click the link for a configuration type, and then check the Contains secrets column in the Summary of key details for the configuration type table.)
   Note: Only perform this step if you prefer to manually create and manage your own secret. If you skip this step, a secret is automatically generated by default to store the Base64-encoded value (specified in spec.data) when you save the configuration.
   1. From the command line, log in to your Red Hat OpenShift cluster by using the oc login command.
   2. Run the following command:

      oc create secret generic secretName --from-file=configuration=configurationFileName --namespace=namespaceName

      Where:

      • secretName is the name of the secret for storing the contents of the configuration file.
      • configurationFileName represents the file path and name of the configuration file.
      • namespaceName is the namespace in which the configuration object will be created. You can omit the --namespace flag if you are already logged in to this namespace.

      Examples:

      oc create secret generic scrt-googleanalytics --from-file=configuration=/mytempdir/accounts.yaml --namespace=mynamespace

      oc create secret generic scrt-googleanalytics --from-file=configuration=C:\mytempdir\accounts.yaml --namespace=mynamespace

   3. Make a note of the secret name so that you can specify it while creating the configuration object.
   4. Leave the command window open.
4. From your local computer, create a YAML file that contains the configuration for the object that you want to create. Include the metadata.namespace parameter to identify the namespace in which you want to create the configuration; this should be the same namespace where the other App Connect instances or resources are created.

   
   To view the full set of parameters and values available, see Custom resource values. (This section also describes how the spec.data value is stored after you create the configuration object.)

   The following YAML code shows an example of what your Configuration custom resource settings should look like if you did not manually create a secret to store the contents of the configuration file. Note that the value of the spec.data parameter must be the Base64-encoded file content that you generated in an earlier step. The metadata.name, metadata.namespace, spec.description, and spec.type values represent your preferred values for the type of configuration being created.

   apiVersion: appconnect.ibm.com/v1beta1
   kind: Configuration
   metadata:
     name: acct-googleanalytics
     namespace: mynamespace
   spec:
     data: ThisRepresentsAveryLongBase64encodedDummyVaLue=
     description: Stores account details for Google Analytics
     type: accounts

   The following YAML code shows an example of what your Configuration custom resource settings should look like if you manually created a secret to store the contents of the configuration file (that contains secrets). Note that the value of the spec.secretName parameter must be the name of this secret.

   apiVersion: appconnect.ibm.com/v1beta1
   kind: Configuration
   metadata:
     name: acct-googleanalytics
     namespace: mynamespace
   spec:
     description: Stores account details for Google Analytics
     secretName: scrt-googleanalytics
     type: accounts

5. Save this file with a .yaml extension; for example, myconfig_cr.yaml.
6. From the command line, run the following command to create the configuration in your Red Hat OpenShift cluster. (Use the name of the .yaml file that you created.)

   oc apply -f myconfig_cr.yaml

   This configuration object is not assigned a status because the object simply represents a document that is referenced in an integration server, integration runtime, the App Connect Dashboard, or App Connect Designer.

7. Run either of the following commands to view the configuration object in your namespace:

   oc get configurations -n namespace

   oc get configurations.appconnect.ibm.com -n namespace

   You should see output that is similar to this for your configuration object and any others that were auto-generated or manually created for a deployed integration server, integration runtime, App Connect Dashboard, or App Connect Designer instance.

   NAME                                        AGE
   acct-googleanalytics                        16h
   des-01-quickstart-ma-designer-acc           16h
   des-01-quickstart-ma-designer-is-adminssl   16h
   des-01-quickstart-ma-designer-ks            16h
   des-01-quickstart-ma-designer-pp            16h
   des-01-quickstart-ma-designer-sc            16h
   des-01-quickstart-ma-designer-sdbp          16h
   des-01-quickstart-ma-designer-ssl           16h
   is-01-quickstart-is-adminssl                16h

What to do next

• If appropriate, you can apply this configuration to an integration server or integration runtime in the same namespace by specifying the metadata.name value of the configuration object in the integration server or integration runtime's spec.configuration setting. For more information, see Integration server reference: Creating an instance from the Red Hat OpenShift web console and Integration runtime reference: Creating an instance from the Red Hat OpenShift web console.

  If created for use with an integration server or integration runtime, you can alternatively apply this configuration to an integration server or integration runtime that you deploy in an App Connect Dashboard instance (that is in the same namespace), as described in Creating an integration server to run your BAR file resources, Creating an integration server to run IBM App Connect Enterprise Toolkit integrations, and Creating an integration runtime to run your BAR file resources.

• If you created a configuration object of type S3Credentials for use with your App Connect Dashboard instance in the same namespace, you can apply this configuration to the Dashboard by specifying the metadata.name value of the configuration object in the Dashboard's spec.storage.s3Configuration setting. For more information, see Dashboard reference: Creating an instance from the Red Hat OpenShift CLI or Kubernetes CLI.
• If you created a configuration object of type S3Credentials for use with your App Connect Designer instance in the same namespace, you can apply this configuration to the Designer instance by specifying the metadata.name value of the configuration object in the Designer's spec.designerMappingAssist.incrementalLearning.storage.s3Configuration setting. For more information, see Designer reference: Creating an instance from the Red Hat OpenShift CLI or Kubernetes CLI.

Updating an instance from the Red Hat OpenShift web console

To update a configuration object by using the Red Hat OpenShift web console, complete the following steps:

1. If required, update the contents of the configuration file (for example, accounts.yaml, generic.zip, or odbc.ini) that was used to create the configuration object. Then run a Base64 encoder against the file and save the generated value. (If the type of configuration contains sensitive data, you can, if preferred, manually create a secret to store the configuration file contents instead of using an auto-generated secret.) For information about the supported configuration types and details about the contents of each file, see Configuration types.
2. From a browser window, log in to the Red Hat OpenShift Container Platform web console. Ensure that you are in the Administrator perspective .
3. From the navigation, click Operators > Installed Operators.
4. If required, select the namespace (project) in which you installed the IBM App Connect Operator.
5. From the Installed Operators page, click IBM App Connect.
6. From the Operator details page for the App Connect Operator, click the Configuration tab.
7. Locate and click the name of the configuration object that you want to update.
8. Click the YAML tab.
9. Update the content of the YAML editor as required.
   If you want to update the content of the configuration object, complete either of the following steps:

   • Add a spec.data entry that is set to the updated Base64-encoded value, and then remove the spec.secretName entry.
   • Overwrite the spec.secretName value with the name of the new secret that you manually created.

   For more information about the available parameters and their values, see Custom resource values.

10. Click Save to save your changes.

Updating an instance from the Red Hat OpenShift CLI or Kubernetes CLI

To update a configuration object from the Red Hat OpenShift CLI, complete the following steps.

1. If required, update the contents of the configuration file (for example, accounts.yaml, generic.zip, or odbc.ini) that was used to create the configuration object. Then run a Base64 encoder against the file and save the generated value. (If the type of configuration contains sensitive data, you can, if preferred, manually create a secret to store the configuration file contents instead of using an auto-generated secret.) For information about the supported configuration types and details about the contents of each file, see Configuration types.
2. From the command line, log in to your Red Hat OpenShift cluster by using the oc login command.
3. From the namespace where the configuration object is deployed, run the oc edit command to partially update the object, where instanceName is the name (metadata.name value) of the configuration object.

   oc edit configuration instanceName

   The configuration CR automatically opens in the default text editor for your operating system.

4. Update the contents of the file as required.
   If you want to update the content of the configuration object, complete either of the following steps:

   • Add a spec.data entry that is set to the updated Base64-encoded value, and then remove the spec.secretName entry.
   • Overwrite the spec.secretName value with the name of the new secret that you manually created.

   For more information about the available parameters and their values, see Custom resource values.

5. Save the YAML definition and close the text editor to apply the changes.

Deleting an instance from the Red Hat OpenShift web console

To delete a configuration object by using the Red Hat OpenShift web console, complete the following steps:

1. From a browser window, log in to the Red Hat OpenShift Container Platform web console. Ensure that you are in the Administrator perspective .
2. From the navigation, click Operators > Installed Operators.
3. If required, select the namespace (project) in which you installed the IBM App Connect Operator.
4. From the Installed Operators page, click IBM App Connect.
5. From the Operator details page for the App Connect Operator, click the Configuration tab.
6. Locate the configuration object that you want to delete.
7. Click the options icon () to open the options menu, and then click the Delete option.
8. Confirm the deletion.

Deleting an instance from the Red Hat OpenShift CLI or Kubernetes CLI

To delete a configuration object from the Red Hat OpenShift CLI, complete the following steps.

1. From the command line, log in to your Red Hat OpenShift cluster by using the oc login command.
2. From the namespace where the configuration object is deployed, run the following command to delete this object, where configurationName is the value of the metadata.name parameter.

   oc delete configuration configurationName