Configuring Container-Based Systems

As a system administrator, you set up and configure your Automic Automation Kubernetes Edition system.

Once your system is deployed, you can configure your system either using the values.yaml file or the relevant sections of the configmap. The values.yaml file that is provided with the AAKE includes examples of default Helm Chart and external database configuration.

Configuring Kubernetes-Specific Components after Deployment

This section comprises different settings that are specific to Kubernetes.

Service Accounts

A default service account is created and automatically mounted into all pods in the namespace, which could be a security risk. Therefore, it is recommended to disable the automount function in the default service account. To do so, set the automountServiceAccountToken parameter to false.

Example

apiVersion: v1
kind: ServiceAccount
metadata:
  name: automic
automountServiceAccountToken: false

Only the operator requires a service account for the installation of AAKE. Therefore, you have to define the name of the dedicated serviceAccount that is used by the operator in the operator: section of the values.yaml file. Make sure you create the service account with the relevant permissions in the namespace.

Example

operator:
  serviceAccount:
    create: true
    name: automic-operator-sa

Service Annotations

Managed Kubernetes services, for example, those provided by AWS, Azure or Google Cloud Platform use different ingress controllers and might require additional annotations in the values.yaml file for the operator, awi, jcp-rest, and jcp-ws services:

Examples

Set GKE annotation for AWI service:

awi:
  service:
    annotations:
      cloud.google.com/neg: '{"ingress": true}'

Set AWS annotation for JCP service:

jcp-ws:
  service:
    annotations:
      service.beta.kubernetes.io/aws-load-balancer-backend-protocol: https

More information:

• Preparing the Ingress and TLS/SSL Certificates

• Connecting to AWI, the JCP and REST Processes Using an Ingress

Configuring your Automic Automation System after Deployment

This section comprises different settings that affect your entire Automic Automation system or a specific component, such as the Automation Engine, the Automic Web Interface, a server process and so on.

Important! When configuring containers, take into account that on-disk files are ephemeral. They are lost when containers or pods stop and restart. To store and refer to resources in the cluster (for example, to files such as logs, traces, images and so on), you must first define the names of the corresponding Persistent Volumes (pv) and Persistent Volume Claims (pvc) in the respective sections of the values.yaml file. For more information about Volumes in Kubernetes please refer to the official Kubernetes product documentation.

Setting Environment Variables after Deployment

In an AAKE environment, you use environment variables to define or change settings for the Automation Engine and the Automic Web Interface. These environment variables not only allow you to substitute values in the AE INI file or the AWI configuration files, they also allow you to define system and other settings.

You can set environment variables using the values.yaml file before or after you install your system. Make sure you carry out a Helm upgrade to apply your changes. The ae and awi pods are restarted automatically.

Note: Make sure you use the correct format when defining environment variables.

Also, after the installation is provided, you can use the ae-properties and awi-properties sections of the configmap to change the respective environment variables. The Install Operator watches the configmap and it restarts all ae and/or awi pods (wp, cp, jcp-rest, jcp-ws, jwp, awi) respectively once you have saved your changes.

More information:

• Automation Engine INI file

• Adapt the Configuration Files for AWI

• Preparing for the Container-Based Installation

• Automic Automation Helm Plugin

Environment Variables for Automation Engine

Each environment variable for the AE uses the syntax pattern ${PREFIX_SECTION_KEY:DEFINITION}:

• PREFIX: AUTOMIC

  Constant prefix for these environment variables.

• SECTION:

  Defines the section of the INI file in which the key you want to define is located.

• KEY:

  Specifies the key you want to substitute.

• DEFINITION:

  The value that you want to define for the key.

The configuration of the Automation Engine server processes is defined in the AE INI file (ucsrv.ini), which comprise all relevant parameters organized in different sections. In an AAKE environment, you can use the values.yaml file to modify these settings before and after the deployment.

Notes:

• Only the system administrator should change parameter values in configuration (INI) files since these kind of changes interfere in and have a great impact in the Automation Engine system.

• You can substitute whole keys of the INI file but not a complete section.

Example

${AUTOMIC_GLOBAL_SYSTEM:AUTOMIC}

This environment variable sets AUTOMIC as the value of the system= key in the [GLOBAL] section of the INI file of the Automation Engine.

After your system is successfully provisioned, you can also use the ae-properties section of the configmap to change these settings, for example, using the following kubectl command to edit it:

kubectl edit configmap ae-properties

Example of the ae-properties configmap

apiVersion: v1
data:
  AUTOMIC_TRACE_TRC03: '1'
  AUTOMIC_REST_CORSSUPPORTENABLED: '1'
  AUTOMIC_REST_CORSACCESSCONTROLALLOWORIGIN: '*'
  AUTOMIC_GLOBAL_STARTMODE: 'COLD'
kind: ConfigMap
metadata:
  ...

You can also use environment variables to set system and other settings that are not part of the AE INI file.

Before the deployment, these variables can be defined only in the values.yaml file. Once your system has been provisioned, you can also modify them using the Automic Web Interface.

For example, you can use them to populate the JCP_ENDPOINT and REST_ENDPOINT parameters of the UC_SYSTEM_SETTINGS variable. To do so, define the respective URLs in the JCP_WS_EXTERNAL_ENDPOINT and JCP_REST_EXTERNAL_ENDPOINT environment variables in the values.yaml file.

Example

JCP_WS_EXTERNAL_ENDPOINT: "https://jcp-ws.<your-domain.example.com>:443"

More information:

• Automation Engine INI file

• Automic Automation Helm Plugin

• Preparing the Ingress and TLS/SSL Certificates

• Connecting to AWI, the JCP and REST Processes Using an Ingress

Environment Variables for AWI

All AWI settings use the syntax pattern ${PREFIX_KEYNAME:DEFINITION}:

• PREFIX: AUTOMIC

  Constant prefix for all AWI settings.

• KEYNAME:

  Matches the property name as defined in the configuration.properties.xml and corlors.properties.xml files. The KEYNAME is written in uppercase and dots are replaces by underscores. For example, the session.colors property becomes AUTOMIC_SESSION_COLORS.

• DEFINITION:

  The value that you want to define for the key

AWI has mandatory and optional configuration files that you must/can modify. In an AAKE environment, you can use the values.yaml file to modify these settings before and after the deployment.

Example

• Environment variable key: AUTOMIC_SSO_SAML_ENABLED

  Value: Specifies whether single sign-on (SSO) can be used for AWI log in

  Example: true

After your system is successfully provisioned, you can also use the awi-properties section of the configmap to change these settings, for example, using the following kubectl command to edit it:

kubectl edit configmap awi-properties

Example of the awi-properties configmap

apiVersion: v1
data:
  AUTOMIC_SYSTEM_NAME: 'AUTOMIC'
  AUTOMIC_CONNECTION_NAME: 'AE_TEST'
  AUTOMIC_MAINCOLOR: '#E61063'
  AUTOMIC_SESSION_COLORS: '#21DE4A,#DE6621,#133AD4'
  AUTOMIC_SSO_SAML_ENABLED: 'true'
kind: ConfigMap
metadata:
    ...

You can also use environment variables to define settings that are not part of any of the AWI configuration files.

Before the deployment, these variables can be defined only in the values.yaml file. Once your system has been provisioned, you can also modify them using the Automic Web Interface.

For example, you can use AUTOMIC_LOGO_BASE64 environment variable to enter the text that corresponds to the AWI logo in BASE64 format.

More information:

• uc4config.xml - Configuring the Connection Between AWI and AE
• logback.xml - Configuring Log Levels
• configuration.properties - Configuring Your Local Setup
• colors.properties - Configuring the Color Scheme

Setting the Log Target

All AE, Analytics and AWI processes write their activities (logs and traces) to the console by default. However, you can also configure a file to which logs, traces and dumps can be written. If you want to write logs and traces to a file, make sure you define a file for each component (jcp-rest, jcp-ws, jwp, cp, wp, analytics, awi, initialdata).

If you want to use a file instead of the console (default), it is mandatory to define the name of the persistent volume claim (pvc name) to which you want to write log/trace files.

Note: Make sure the access nodes of the PV and PVC you use are set to ReadWriteMany if the pods that access them run on different nodes. If all pods run on a single node, you can also set them to ReadWriteOnce.

Example

apiVersion: v1
kind: PersistentVolume
metadata:
  name: pv-logging
spec:
  storageClassName: manual
  capacity:
    storage: 4Gi
  accessModes:
    - ReadWriteMany
  hostPath:
    path: /home/luf/helm/log
---
apiVersion: v1
kind: PersistentVolumeClaim
metadata:
  name: pvc-logging
spec:
  storageClassName: manual
  accessModes:
    - ReadWriteMany
  resources:
    requests:
      storage: 2Gi

For more information and examples of persistent volumes and persistent volume claims, see the official Kubernetes documentation.

In the values.yaml file, change the definition of the log and trace parameters from console to file to write the log and trace to the corresponding pvc.

Example

logging:
    pvc:   pvc-logging
    log:   file
    trace: file

Make sure you carry out a Helm update to apply your changes. The ae and awi pods are restarted automatically.

By default, log and trace files are overwritten every time the system is restarted. To keep older files for later use, you can specify the number of history files to be kept by changing the trace level in the respective section of the configmap.

The history files are named 01, 02, and so on, and are moved with every restart. The oldest file (with the highest number) is deleted and all other files are renamed (number is increased by 1).

More information:

• Logging/Trace

• Configuring the Logging in AWI

Setting the Custom Logo

You can customize the logo that is displayed in the AWI menu bar using two environment variables, one to set the image and another one to specify the MIME type. You configure the custom logo in the [environment] > [AWI] > [logo] section of the values.yaml file.

Prerequisite: You have already defined the pvc and pv names.

1. To specify the image add and configure one of the following environment variables:

   • AUTOMIC_LOGO_BASE64

     Use this variable to enter the text that corresponds to the image in BASE64 format.

   • AUTOMIC_LOGO_FILENAME

     Use this variable to enter the name of the image file.

2. Specify the MIME type.

   Add and configure an AUTOMIC_LOGO_MIMETYPE variable for image types other than .PNG.

Changing the AE Certificate within the Cluster

Within the Kubernetes cluster all the communication is encrypted. The jcp-ws, jcp-rest, and awi services by default use generated, self-signed certificates; therefore, you do not have to prepare a TLS/SSL certificate for them. These certificate are stored using standard Kubernetes TLS secrets and using the name of the respective service: jcp-ws-cert, jcp-rest-cert, awi-cert.

Optionally, you can replace one or more of the generated, self-signed certificates with custom ones and configure them accordingly.

Note: Make sure that you still use the names jcp-ws-cert, jcp-rest-cert, awi-cert even if you use a custom certificate.

If you do not use custom ones for all services, the remaining ones are generated automatically.

To use custom certificates, you have to do the following before the installation:

1. Depending on how you want to connect to the system, define either the IP address or DNS name for the Subject Alternative Name (SAN). You can choose multiple SANs

2. Create the Kubernetes TLS secret using the certificate and key files. For example, to use a custom certificate for AWI (awi-cert) you can execute the following command:

   kubectl create secret tls awi-cert --cert=path/to/awi.crt --key=path/to/awi.key

3. Make sure that you run the AAKE installation in the same namespace in which you created the secret.

4. Connect to the respective service (jcp-ws, jcp-rest, awi) using one of the Subject Alternative Name (SAN) addresses and the port of the service.

Note: The install operator creates the Java KeyStores automatically.

More information:

• TLS/SSL Certificate Considerations

• Preparing the Ingress and TLS/SSL Certificates

• Connecting to AWI, the JCP and REST Processes Using an Ingress

• Securing Connections to the AE (TLS/SSL)

Changing the AE DB Password

When you change the password of the AE database, make sure that the ae-db secret that you created while preparing for the AAKE installation is updated with the new DB password. For more information, see Preparing the AE and Analytics Databases for the Container Installation.

You also need to update the password in the ae secret containing the DB connection strings.

The AAKE pods must be restarted to use the new password.

See also:

• Preparing for the Container-Based Installation
• Installing and Migrating Container-Based Systems
• Configuration (INI) Files
• uc4config.xml - Configuring the Connection Between AWI and AE