Configuration reference

Use this reference to create, update, or delete configuration objects for integration servers, the App Connect Dashboard, or App Connect Designer by using the Red Hat® OpenShift® web console or CLI, or the CLI for a Kubernetes environment.

Introduction

The Configuration API enables you to create configuration objects for the following IBM® App Connect instances or components:

  • Integration servers: You can create configuration objects of various types, which can be used to configure integration servers; for example, server.conf.yaml, policy projects, or accounts.yaml definitions. The custom resource settings for a configuration object identify the type of configuration and the associated content (in binary format) that should be applied to an integration server. When you create an integration server, you can add references to the configuration objects that you want to apply.
    Tip: Configuration objects can also be created from an App Connect Dashboard instance, and applied to BAR files that are deployed as integration servers. The App Connect Dashboard can also be used to update or delete configuration objects. For more information, see Deploying IBM App Connect Designer flows and APIs to integration servers, Deploying IBM App Connect Enterprise Toolkit integrations to integration servers, and Configuration types for integration servers.

  • App Connect Dashboard: You can create a configuration object of type S3Credentials, which can be used to configure an App Connect Dashboard instance at version 12.0.1.0-r1 or later. If you want to enable an App Connect Dashboard instance to use a Simple Storage Service (S3) bucket to store BAR files that you upload or import to the content server for the Dashboard, you can use this configuration type to specify credentials for accessing the S3 bucket. When you create an App Connect Dashboard instance, you can reference a single configuration object of type S3Credentials that you want to apply. For more information about this configuration type, see Dashboard reference: Storage and Creating, updating, or deleting a configuration of type S3Credentials for use with the App Connect Dashboard.
    Note: Configuration objects of type S3Credentials cannot be created from an App Connect Dashboard instance and are not visible in the Dashboard UI.

  • App Connect Designer: You can create a configuration object of type S3Credentials, which can be used to configure an App Connect Designer instance at version 12.0.1.0-r4 or later. If you want to enable an App Connect Designer instance to use a Simple Storage Service (S3) bucket to store the trained artificial intelligence (AI) model for the incremental learning feature, you can use this configuration type to specify credentials for accessing the S3 bucket. When you create an App Connect Designer instance, you can reference a single configuration object of type S3Credentials that you want to apply. For more information about this configuration type, see Designer reference: Storage and Creating, updating, or deleting a configuration of type S3Credentials for use with App Connect Designer.

Prerequisites

Red Hat OpenShift SecurityContextConstraints requirements

IBM App Connect runs under the default restricted SecurityContextConstraints.

Creating an instance

You can create a configuration object by using the Red Hat OpenShift web console or CLI, or the CLI for a Kubernetes environment.

Tip: Any configuration object that you create for use with integration servers by using the Red Hat OpenShift web console or CLI, or Kubernetes CLI will automatically be added to the configurations table in an App Connect Dashboard instance that is in the same namespace.


Considerations for creating an instance

  • If you need to create a configuration object of type Agentx, alternative steps for obtaining a default configuration from your switch server are provided in the App Connect Integration Server reference.
  • By default, when you deploy an integration server, a configuration object of type REST Admin SSL files is automatically created and applied to that integration server. For more information, see REST Admin SSL files type.

Before you begin

Ensure that the Prerequisites are met.

Namespace restriction for an instance, server, configuration, or trace:

The namespace in which you create an instance or object must be no more than 40 characters in length.


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.
    Note: 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. Applicable to IBM Cloud Pak for Integration only:
    1. If not already logged in, log in to the IBM Cloud Pak Platform UI for your cluster.
    2. From the Platform UI home page, click Install operators or OpenShift Container Platform, and log in if prompted.
  4. Applicable to an independent deployment of IBM App Connect Operator only: From a browser window, log in to the Red Hat OpenShift Container Platform web console.
  5. 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.
  6. From the navigation, click Operators > Installed Operators.
  7. If required, select the namespace (project) in which you installed the IBM App Connect Operator.
  8. From the Installed Operators page, click IBM App Connect.
  9. From the Operator Details page for the App Connect Operator, click the Configuration tab. Any previously created configuration objects are displayed in a table.
  10. Click Create Configuration.
    Tip: 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.
  11. 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.
  12. 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
  13. 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, the App Connect Dashboard, or App Connect Designer.
  14. 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

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.

Note: These instructions relate to the Red Hat OpenShift CLI, but can be applied to a Kubernetes environment by using the relevant command to log in to the cluster, and substituting oc with kubectl where appropriate.
  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.
    Note: 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, the App Connect Dashboard, or App Connect Designer.

What to do next

Updating the custom resource settings for an instance

If you want to change the content or settings of an existing configuration object, you can edit its custom resource settings by using the Red Hat OpenShift web console or CLI, or the CLI for a Kubernetes environment. For example, you might want to update the Base64-encoded value of a configuration object if the stored credentials have changed.

Restriction: You cannot update standard settings such as the kind of resource (kind), and the name and namespace (metadata.name and metadata.namespace), as well as some system-generated settings, or settings such as the storage type of certain components. An error message will be displayed when you try to save.

Ensure that you have cluster administrator authority or have been granted the appropriate role-based access control (RBAC).


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. Applicable to IBM Cloud Pak for Integration only:
    1. If not already logged in, log in to the IBM Cloud Pak Platform UI for your cluster.
    2. From the Platform UI home page, click Install operators or OpenShift Container Platform, and log in if prompted.
  3. Applicable to an independent deployment of IBM App Connect Operator only: From a browser window, log in to the Red Hat OpenShift Container Platform web console.
  4. From the navigation, click Operators > Installed Operators.
  5. If required, select the namespace (project) in which you installed the IBM App Connect Operator.
  6. From the Installed Operators page, click IBM App Connect.
  7. From the Operator Details page for the App Connect Operator, click the Configuration tab.
  8. Locate and click the name of the configuration object that you want to update.
  9. Click the YAML tab.
  10. 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.

  11. 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.

Note: These instructions relate to the Red Hat OpenShift CLI, but can be applied to a Kubernetes environment by using the relevant command to log in to the cluster, and substituting oc with kubectl where appropriate.
  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.
Tip: You can also use commands such as oc patch to apply a patch to the CR if preferred.

Deleting an instance

If no longer required, you can delete a configuration object by using the Red Hat OpenShift web console or CLI, or the CLI for a Kubernetes environment.

Ensure that you have cluster administrator authority or have been granted the appropriate role-based access control (RBAC).

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. Applicable to IBM Cloud Pak for Integration only:
    1. If not already logged in, log in to the IBM Cloud Pak Platform UI for your cluster.
    2. From the Platform UI home page, click Install operators or OpenShift Container Platform, and log in if prompted.
  2. Applicable to an independent deployment of IBM App Connect Operator only: From a browser window, log in to the Red Hat OpenShift Container Platform web console.
  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 the configuration object that you want to delete.
  8. Click the options icon (Options menu) to open the options menu, and then click the Delete option.
  9. 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.

Note: These instructions relate to the Red Hat OpenShift CLI, but can be applied to a Kubernetes environment by using the relevant command to log in to the cluster, and substituting oc with kubectl where appropriate.
  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

Custom resource values

The following table lists the configurable parameters and default values for configuration objects.

Parameter Description Default

apiVersion

The API version that identifies which schema is used for this object.

appconnect.ibm.com/v1beta1

kind

The resource type.

Configuration

metadata.name

A unique short name by which the configuration object can be identified.

metadata.namespace

The namespace (project) in which the configuration object is installed.

The namespace in which you create an instance or object must be no more than 40 characters in length.

spec.contents

If the type of configuration that you are creating does not contain secrets, spec.contents is used to store the Base64-encoded value (of a configuration file) that you specify in spec.data. The value is automatically transferred from spec.data to spec.contents after you create the configuration.

Note: In 11.0.0.9-r3 or earlier versions, spec.contents is used for the manual input of Base64-encoded content. Manual input in this field is no longer recommended in later versions.

spec.data

(Only applicable if spec.version resolves to 11.0.0.10-r1 or later)

The Base64-encoded content of a configuration file. For information about these configuration files, see Configuration types.

If the type of configuration that you are creating does not contain secrets, specify the Base64-encoded value in spec.data. This value is automatically transferred to spec.contents after you create the configuration.

If the type of configuration that you are creating contains secrets (sensitive data), the Base64-encoded value needs to be stored in a secret to keep it secure. You can either create your own secret, or have the IBM App Connect Operator create one for you:

  • Specify the Base64-encoded value in spec.data without creating a secret. The value will be automatically converted to a secret and transferred to spec.secretName after you create the configuration.
  • Omit spec.data and instead manually create a secret for the Base64-encoded value. Then specify this secret in spec.secretName.
 

spec.description

A description of the configuration object.

spec.secretName

The name of an auto-generated or manually created secret that stores the content of a configuration that contains secrets (sensitive data).

  • If the type of configuration that you are creating contains secrets, the Base64-encoded value that you specify in spec.data will be automatically converted to a secret and transferred to spec.secretName after you save. The name of this secret is generated as configurationName-generatedCharacters, where configurationName is the metadata.name value.
  • If you would prefer to create your own secret, manually create one for the Base64-encoded value and then specify this secret in spec.secretName. In this case, you do not need to specify a value for spec.data.

    You can create a secret by using the Red Hat OpenShift web console or CLI, as described in Creating an instance from the Red Hat OpenShift web console or Creating an instance from the Red Hat OpenShift CLI or Kubernetes CLI.

 

spec.type

The type of configuration.

Valid values for integration servers are as follows. For more information about each configuration type, see Configuration types (or Configuration types for integration servers).
  • accounts
  • adminssl
  • agenta
  • agentx
  • barauth
  • generic
  • keystore
  • loopbackdatasource
  • odbc
  • persistencerediscredentials
  • policyproject
  • resiliencekafkacredentials
  • serverconf
  • setdbparms
  • truststore
  • truststorecertificate
  • workdiroverride

Valid values for an App Connect Dashboard instance are as follows. For more information about this configuration type, see Creating a configuration of type S3Credentials for use with the App Connect Dashboard.
  • s3credentials

Valid values for an App Connect Designer instance are as follows. For more information about this configuration type, see Creating a configuration of type S3Credentials for use with App Connect Designer.
  • s3credentials