Integration Server Configuration reference

Use this reference to create and delete configuration objects for integration servers by using the Red Hat® OpenShift® web console or CLI.

Introduction
Prerequisites
Red Hat OpenShift SecurityContextConstraints requirements
Creating an instance
Deleting an instance
Custom resource values
Limitations

Introduction

The Integration Server Configuration API enables you to create objects that can be used to configure integration servers; for example, server.conf.yaml, policy projects, or accounts.yaml definitions. The custom resources that you define 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. For more information, see Configuration types for integration servers.

Prerequisites

Red Hat OpenShift Container Platform 4.6 is required for EUS compliance. Red Hat OpenShift Container Platform 4.10 is also supported for migration from EUS to a Continuous Delivery (CD) or Long Term Support (LTS) release.
For any production licensed instances, you must create a secret called ibm-entitlement-key in the namespace where you want to create IBM App Connect resources. For more information, see IBM Entitled Registry entitlement keys.

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.

Tip: Any configuration object that you create from the Red Hat OpenShift web console or 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. The configuration object is generated by using a predefined ZIP file that contains self-signed certificates, together with a secret that stores the contents of this ZIP file. The configuration object is created with a metadata.name value of integrationServerName-is-adminssl, where integrationServerName is the assigned name of the integration server. The secret is also generated with the name integrationServerName-is-adminssl, which is then set as the spec.secretName value. The predefined ZIP file contains three PEM files, which are added to the /home/aceuser/adminssl directory:
- ca.crt.pem: The certificate authority (CA) certificate
- tls.crt.pem: The TLS certificate
- tls.key.pem: The TLS key
  
  In the YAML view for the integration server's definition, this default configuration is enabled through the following setting, which is set to true by default:
```
spec:
  adminServerSecure: true
```
It is expected that you would create a configuration object of type REST Admin SSL files only if you want to use certificates from your own trusted CA instead of using the pre-supplied self-signed certificates. To set up REST Admin SSL with certificates that are signed by your preferred CA, complete the following steps:
1. Create your certificate PEM files with identical names as the default names that are used for an auto-generated configuration: ca.crt.pem, tls.crt.pem, and tls.key.pem.
2. Create a configuration object of type REST Admin SSL files, as described Creating an instance from the Red Hat OpenShift web console in and Creating an instance from the Red Hat OpenShift CLI.

Before you begin

The IBM App Connect Operator must be installed in your cluster either through a standalone deployment or an installation of IBM Cloud Pak for Integration. For further details, see the following information:
- Installing the IBM App Connect Operator
- Installing IBM Cloud Pak for Integration
Ensure that you have cluster administrator authority or have been granted the appropriate role-based access control (RBAC).
Namespace restriction for an instance, server, or configuration:
The namespace in which you install must be no more than 40 characters in length.

Create options:

Creating an instance from the Red Hat OpenShift web console
Creating an instance from the Red Hat OpenShift CLI

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:

Create the type of configuration file that you require; for example, accounts.yaml, generic.zip, or odbc.ini. For more information about configurations, see Configuration types for integration servers.
Note: The maximum recommended size of a ZIP file for a configuration is approximately 660 KB.
Run a Base64 encoder against the file and save the contents.
Applicable to IBM Cloud Pak for Integration only:
1. If not already logged in, log in to the Platform Navigator for your cluster.
2. From the IBM Cloud Pak menu , click OpenShift Console and log in if prompted.
Applicable to an IBM App Connect Operator deployment only: From a browser window, log in to the Red Hat OpenShift Container Platform web console.
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. (See Configuration types for integration servers for information about which configuration types contain secrets.)
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, and then specify the Base64-encoded content in the Value field.
5. Click Create.
6. Make a note of the secret name so that you can specify it while creating the configuration object.
From the navigation, click Operators > Installed Operators.
If required, select the namespace (project) in which you installed the IBM App Connect Operator.
From the Installed Operators page, click IBM App Connect.
From the Operator Details page for the App Connect Operator, click the Integration Server Configuration tab. Any previously created configuration objects are displayed in a table.
Click Create Configuration. Switch to the YAML view if necessary for a finer level of control over your installation settings. The minimum custom resource (CR) definition that is required to create a configuration object is displayed.
From the Details tab on the Operator Details page, you can also locate the Integration Server Configuration tile and click Create Instance to specify installation settings for the configuration object.
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 the custom field definitions of your configuration object should look like if you did not manually create a secret to store the Base64-encoded content 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.
```
apiVersion: appconnect.ibm.com/v1beta1
kind: Configuration
metadata:
  name: setdbp-conf
  namespace: mynamespace
spec:
  data: ABCDefghIJLOMNehorewirpewpTEV843BCDefghIJLOMNorewirIJLOMNeh842lkalkkrmwo4tkjlfgBCDefghIJLOMNehhIJLOMNehBCD
  description: Stores the IBM Cloud API key for productapi
  type: setdbparms
```
The following YAML code shows an example of what the custom field definitions of your configuration object should look like if you manually created a secret to store the Base64-encoded content 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: setdbp-conf
  namespace: mynamespace
spec:
  description: Stores the IBM Cloud API key for productapi
  secretName: setdbpproductapi
  type: setdbparms
```
Optional: If you prefer to use the Form view, click Form View and then complete the fields. Note that some fields might not be represented in the form.
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.
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.

You can apply this configuration to any integration server in the same namespace by specifying the metadata.name value of the configuration object in the integration server's spec.configuration value. For more information, see Creating an instance from the Red Hat OpenShift web console. You can alternatively apply this configuration to an integration server 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 and Creating an integration server to run IBM App Connect Enterprise Toolkit integrations.

Creating an instance from the Red Hat OpenShift CLI

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

Create the type of configuration file that you require; for example, accounts.yaml, generic.zip, or odbc.ini. For more information about configurations, see Configuration types for integration servers.
Note: The maximum recommended size of a ZIP file for a configuration is approximately 660 KB.
Run a Base64 encoder against the file and save the contents.
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. (See Configuration types for integration servers for information about which configuration types contain secrets.)
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-literal=configuration=configurationContent --namespace=namespaceName
```
  Where:
  - secretName is the name of the secret for storing the Base64-encoded configuration content.
  - configurationContent is the Base64-encoded configuration content.
  - 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.
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.
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 the custom field definitions of your configuration object should look like if you did not manually create a secret to store the Base64-encoded content 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.
```
apiVersion: appconnect.ibm.com/v1beta1
kind: Configuration
metadata:
  name: setdbp-conf
  namespace: mynamespace
spec:
  data: ABCDefghIJLOMNehorewirpewpTEV843BCDefghIJLOMNorewirIJLOMNeh842lkalkkrmwo4tkjlfgBCDefghIJLOMNehhIJLOMNehBCD
  description: Stores the IBM Cloud API key for productapi
  type: setdbparms
```
The following YAML code shows an example of what the custom field definitions of your configuration object should look like if you manually created a secret to store the Base64-encoded content 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: setdbp-conf
  namespace: mynamespace
spec:
  description: Stores the IBM Cloud API key for productapi
  secretName: setdbpproductapi
  type: setdbparms
```
Save this file with a .yaml extension; for example, myconfig_cr.yaml.
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.

You can apply this configuration to any integration server in the same namespace by specifying the metadata.name value of the configuration object in the integration server's spec.configuration value. For more information, see Creating an instance from the Red Hat OpenShift CLI. You can alternatively apply this configuration to an integration server 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 and Creating an integration server to run IBM App Connect Enterprise Toolkit integrations.

Deleting an instance

If no longer required, you can uninstall a configuration object by deleting it. You can delete an object by using the Red Hat OpenShift web console or CLI.

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

Delete options:

Deleting an instance from the Red Hat OpenShift web console
Deleting an instance from the Red Hat OpenShift CLI

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:

Applicable to IBM Cloud Pak for Integration only:
1. If not already logged in, log in to the Platform Navigator for your cluster.
2. From the IBM Cloud Pak menu , click OpenShift Console and log in if prompted.
Applicable to an IBM App Connect Operator deployment only: From a browser window, log in to the Red Hat OpenShift Container Platform web console.
From the navigation, click Operators > Installed Operators.
If required, select the namespace (project) in which you installed the IBM App Connect Operator.
From the Installed Operators page, click IBM App Connect.
From the Operator Details page for the App Connect Operator, click the Integration Server Configuration tab.
Locate the configuration object that you want to delete.
Click the options icon () for that row to open the options menu, and then click the Delete option.
Confirm the deletion.

Deleting an instance from the Red Hat OpenShift CLI

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

From the command line, log in to your Red Hat OpenShift cluster by using the oc login command.
Run the following command to delete the configuration 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 install 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 for integration servers. 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. Note: If you want to update a configuration by using the Red Hat OpenShift web console, open the configuration and switch to YAML view. Then either set a spec.data value with spec.secretName omitted, or specify a manually created secret name for the updated Base64 contents in spec.secretName. If you want to update a configuration by using the Red Hat OpenShift CLI, either overwrite the spec.data value in the YAML file with updated Base64-encoded content, or overwrite the spec.secretName value with the name of a secret that stores the updated Base64-encoded content.
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.
spec.type	The type of configuration. Valid values are as follows: `accounts` `adminssl` `agenta` `agentx` `generic` `keystore` `loopbackdatasource` `odbc` `policyproject` `serverconf` `setdbparms` `truststore` `truststorecertificate` For more information about each configuration type, see Configuration types for integration servers.

Limitations

Supports only the amd64 and s390x CPU architectures. For more information, see Supported platforms.