Customization in Container environment

Last modified 22 Feb 2024 23:39 +01:00
Table of Contents

Customization of the containers

The image is prepared to be flexible in usage. All the common settings should be possible to realize without rebuilding the image.

To change the setting the available options are covered by the file located in /opt/midpoint/bin/midpoint.sh.

There are two ways how the file can be used .

  • MP_SET_ environment variable
    This part cover the most flexible part of the possible customization of the image.

  • Environment initiation
    This part covert all the common needs related to the init of the environment (first run).

Bash script defining also TRAPs.
Without this definition the TERM or KILL signal would not be passed to the midPoint application in case of shutting down of the container. This situation would not provide application time to properly ends operation.
With the defined TRAPs signal properly reach the midPoint application and the operations are properly finished.
From user point of view the termination of the container doesn’t need to wait 10s timeout before environment forcing to kill the container and in read the termination take just few seconds.

Environment initiation

This section is focused on handling available files. What exactly will happen is controlled by the environment variables. There are available several environment variables. Following logic is applied only in case the relevant environment variable is set.

Once the required variable is set there is need to run midpoint.sh init-native. This process will od all required operations.

  • MP_CHECK
    Touch file (can be empty) which existence is checked during midpoint start. Once the file exists it prevent start of application. It the file is missing (or it is removed) the start continue as usual.

    example of the value
    MP_CHECK=/opt/midpoint/var/init_in_progress

    The usage is mainly in advanced scenarios when there is need to force midPoint to wait until the external condition is met. In the most common use cases this option will not be useful.

  • MP_INIT_CFG
    The default config.xml file is prepared for the generic repository. Sample config.xml file for the native repository contain all we need to have set. All the rest of the configuration can be set / overwrite by the MP_SET_ prefixed environment variables. Using this variable the native repository sample config.xml file will be copied (and properly renamed) to the directory set by the value of the variable.

    example of the value - target directory is /opt/midpoint/var (file will be /opt/midpoint/var/config.xml)
    MP_INIT_CFG=/opt/midpoint/var

    This option is needed all the time until there is available persistent storage (volume) for the home directory.

  • MP_DB_PW
    The password for the database access has to be the same on the client and server side. As far as the roles are split, the password has to be set in advance to be the same on both side of communication. The value is the path to the file, where the generated password should be saved.

    example of the value - the generated password will be saved to /opt/db-pw/dbpassword
    MP_DB_PW=/opt/db-pw/dbpassword

    In case of generating of the password the step has to be done before the DB container is started. As the preferred repository initiation is push (object is created remotely in the already running database) this cannot be done in one step. Generating of the password for the database mean two phase init container - one for DB PW generation and second one for the repo init.

  • MP_PW
    In case you prefer to have your own generated password for keystore, this option will interest you. As a value the location for the file is provided.

    example of the value - the generated password will be saved to /opt/midpoint/var/keystorepw
    MP_PW=/opt/midpoint/var/keystorepw

    Once the password is used there have to be set the file as keystore password for the midPoint container otherwise the default "changeit" will be used.

Environment variables

  • MP_MP_ENTRY_POINT
    The entry point can be used to copy some file before the system start. It is usable mainly with container approach like Docker.

  • MP_MEM_MAX
    Alias for JAVA_OPTS variable -Xmx[0-9]. It may be usefull especially in case the "simply" key=value syntax would be prefered to the complex set of values in one variable.

  • MP_MEM_INIT
    Alias for JAVA_OPTS variable -Xms[0-9]. It may be usefull especially in case the "simply" key=value syntax would be prefered to the complex set of values in one variable.

  • MP_SET_
    To make the passing the variable for java easier there has been set "mapping" for the environment variables starting with MP_SET_. The result will be -D parameters in JAVA_OPTS which is already passed to java process. The benefit is in maintaining configuration mainly for midpoint run in the containers where passing additional argument mean list all of them and not only new one. With this mapping it is easier to maintain or even generate the configuration for the container instance.

    By the processing MP_SET_ "prefix" is removed and for the rest there is replaced _ with . (dot). The is exception _FILE which is handled. The prefix -D is added and the final result is added to the JAVA_OPTS variable which is used for the starting.

MP_SET_ example

  • config.xml - repository configuration
    One of the usage for MP_SET_ prefixed environment variable is repository configuration.

    subset of the config.xml (for illustration only)
    <?xml version="1.0"?>
<configuration>
    <midpoint>
        <repository>
            <jdbcUrl>jdbc:postgresql://localhost:5432/midpoint</jdbcUrl>
            <jdbcUsername>midpoint</jdbcUsername>
        </repository>
    </midpoint>
</configuration>

    In case we want to set / overwrite these values the following structure of environment variables should be used :

    environment variable in Docker-compose syntax
    service:
  <service_name>:
    environment:
     - MP_SET_midpoint_repository_jdbcUrl=jdbc:postgresql://localhost:5432/midpoint
     - MP_SET_midpoint_repository_jdbcUsername=midpoint
    environment variable in Kubernetes syntax
    spec:
  containers:
    - name: <container_name>
      env:
        - name: MP_SET_midpoint_repository_jdbcUrl
          value: 'jdbc:postgresql://localhost:5432/midpoint'
        - name: MP_SET_midpoint_repository_jdbcUsername
          value: 'midpoint'
    environment variable in Docker syntax
    docker run -e MP_SET_midpoint_repository_jdbcUrl=jdbc:postgresql://localhost:5432/midpoint -e MP_SET_midpoint_repository_jdbcUsername=midpoint ...

  • embedded Tomcat
    Other usage is to change embedded Tomcat setting.

    subset of server properties (application.yml)
    server:
  port: 8080 # Server HTTP port.

    As a example we can change the port from 8080 to 8081.

    MP_SET_server_port=8081

Entry Point

MP_ENTRY_POINT option is pointing to the folder in the container’s filesystem, which is handled as a read only source mainly for post-initial-objects. The content is copied to proper midpoint’s structure (/opt/midpoint/var) before starting the midpoint instance with keeping the same sub folder structure.

During the processing of the MP_ENTRY_POINT it checks the existence of the file or file with extension .done (processed post-initial-object is renamed with suffix .done). Once the file in any form ("exact" name or with the .done suffix) exists, the file is skipped so any future changes on the copied version are kept without overwriting - only new files are copied. This way the post-initial-objects can be re-used several times with the same behaviour all the time.

example of the behaviour : MP_ENTRY_POINT=/opt/entry-point
/opt/entry-point
- post-initial-objects
  + user.xml
  - role.xml

/opt/midpoint/var
+ post-initial-objects
  - user.xml.done

  • post-initial-objects exists so no change

  • user.xml in the destination there exists user.xml.done so no action will happen

  • role.xml does not exist so it will be copied to /opt/midpoint/var/post-initial-objects/role.xml

In the theory you can mount it directly to the midpoint’s structure but the resulting behaviour will be, the most probably, a little bit different than expected. With the first run there can be two possible situations:

  • the mount point will be in "writable" mode
    In that case the file will be renamed with adding suffix ._done and respective next run (with new container) will be ignoring the files.

  • the mount point will be read-only mode
    The midpoint start will fail and it will not be possible to rename the file, which is handled as critical error.

If MP_ENTRY_POINT feature is not needed the following lines can be removed:

kubernetes syntax
- MP_ENTRY_POINT=/opt/midpoint-dirs-docker-entrypoint
docker syntax
- ./midpoint_server/container_files/mp-home:/opt/midpoint-dirs-docker-entrypoint/:ro

In case the lines are kept in the example, the directory ./midpoint_server/container_files/mp-home should exists. Otherwise docker-compose will create it. As the container runs under root the newly created directory will have the permission set (UID, GID) for the root user. To prevent this behavior prepare the directory structure in advance.

Volumes

Until you will attach the volume all the changes are kept only in the container which may be discarded. The image is ready to attach the volume to midPoint home - /opt/midpoint/var. By attaching the external store (volume) you will keep stored data from midPoint home out of container. This way it is safe to remove the container and create new one attaching the volume (changing image version - e.g. new support branch build)

Volumes are handled in the container similar to mount points. There may be more volumes mapped in cascade.

midpoint structure
/opt/midpoint/var
+ connid-connectors
+ export
+ icf-connectors
| - connector-ssh-1.0.jar
+ idm-legacy
+ import
+ lib
| + jython-standalone-2.7.2.jar
| - ojdbc11.jar
+ log
| + midpoint.out
| - midpoint.log
+ post-initial-objects
+ schema
+ tmp
+ trace
- work
local filesystem structure
/tmp/workdir
+ connectors
| - connector-ssh-1.0.jar
- docker-compose.yml

In case you want to attach the subdirectory with the connector to container the following definition should be used :

binding directory from external filesystem to container (docker syntax)
- ./connectors:/opt/midpoint/var/connid-connectors

There is also option to bind directly the file. .binding specific file from external filesystem to container (docker syntax)

- ./connectors/connector-ssh-1.0.jar:/opt/midpoint/var/connid-connectors/connector-ssh-1.0.jar

Once you will use the volume / mount point the original content will be hidden. Based on the usage the original content can be copied but not in all the cases.
Was this page helpful?
YES NO
Thanks for your feedback