About the contract

The auths subsection

The auths section consists of information about the container's registry. If a public image is used in the contract, then you do not need the auths section because no credentials are required. The auths subsection is required only if the container images are private. This subsection does not have any image information, as shown in the following sample. This subsection needs to contain the name of the image registry and the credentials such as username-password for the same. The key must be the hostname of the container registry or the string 'https://index.docker.io/v1/' for the default docker registry.

The following snippet shows an example for IBM Cloud Registry. For more information about using the API key, see Using client software to authenticate in automation.

auths:
  us.icr.io:
    password: <apikey>
    username: iamapikey

The compose subsection

It consists of an archive subsection. The archive subsection contains the Base64 encoded TGZ file archive of the docker-compose.yaml file. As the Hyper Protect Container Runtime image uses Docker Engine and Docker Compose to start the container, the information about the container must first be created by using a standard docker-compose file. This file is then archived and base64 encoded and the output of this is provided as the value to the archive subsection, within the compose section. For more information, see Overview of Docker Compose.

You must use an image that you built and update information about the image in the image section of the docker-compose.yaml file. You cannot use Docker Compose to build the image.

The mount points that are specified under the volumes section of the docker-compose.yaml file must be aligned with the volumes "mount" field that is specified in the workload section of the contract. For example, the value for volumes that are shown in the example of a docker compose file is /mnt/data/var/www/html:/var/www/html, where /mnt/data must match the mount point that is specified in the mount field (mount: /mnt/data) in the volumes section of the workload.

Note: Executing a build as part of a docker compose file is not supported. Make sure your docker compose file doesn't have a build section.

Both "yaml" and "yml" formats are supported for docker-compose file. The following is an example of a docker-compose file.

services:
  nc:
    image: nextcloud:apache
    restart: always
    ports:
      - 80:80
    volumes:
      - /mnt/data/var/www/html:/var/www/html
    environment:
      - REDIS_HOST=redis
      - MYSQL_HOST=db
      - MYSQL_DATABASE=nextcloud
      - MYSQL_USER=nextcloud
      - MYSQL_PASSWORD=nextcloud

Tip: There are use cases where the registry is not known when the workload section is pre-encrypted. For example, when the workload provider wants to allow the deployer to use a registry mirror or a secure private container registry. In such a case, it's possible to dynamically override the registry as well as the pull credentials. This is a coordinated effort between the workload provider and the deployer. For more information, see Using a dynamic registry reference.

Use the following command to get the base64 encoded archive file. The base64 output is available in the compose.b64 file.

tar czvf - -C <COMPOSE_FOLDER> . | base64 -w0 > compose.b64

Note: Make sure that the compose tgz file only contains directories and regular files. Links or pipes are not supported.

Copy the content of compose.b64 as a value of compose -> archive.

compose:
  archive: <paste the content of compose.b64 >

For this example, you would see a response similar to the following output:

compose:
  archive: H4sIAKOFmGIAA+2RTW6DMBBGs84pRuyB8Q8k+DIRwZOGtmBkkyrcvhgnLVVV1EWkqhJv4ZHt8ednWZvqhWxcmaYzjpKhed08HETMpQRfd3k2VeRhPpEJCUxymTPkIuOALBOIG8DHq3zn4vrSjiqdLY/nsv+xb2w7nRZywlPgo/4THNm3uiKntgCWdO1aowmZnwLUTflECpwo8Jpu9NyZ2zvQgdADFEudoXyQzSu+fPPzseSvedo6qjV7mDa2anZbdH8totL6somtUlvX8K4SJshDsFKU2NmFvAZuMc9U37wceeys+Y6BI8Fi6+6vxK5RS+YFDh6RNu//tuVlZWVJd4BcjKckQAIAAA=

The play subsection

In the play subsection, you can define the workload via Pod descriptors. Each pod can contain one or more container definitions. Descriptors can be provided in one of the following ways:

• In plain YAML format in the resources subsection of play. This section is an array of descriptors and supports two types of descriptors: Pods and ConfigMaps.

  The following example illustrates how to use the resources section:

  workload: |
    type: workload
    play:
      resources:
        - apiVersion: v1
          kind: Pod
          metadata:
            name: busybox
          spec:
            containers:
            - name: main
              image: ...
              command:
              - printenv
              envFrom:
              - configMapRef:
                  name: contract.config.map
                  optional: false
            restartPolicy: Never
  

• In the archive subsection of play, the archive is a base64 encoded, gzipped tar file. The Pods or ConfigMaps are represented as YAML files, at the top level in this tar file. The file may also contain extra files and all files will be extracted to the host file system before starting the Pods. The current working directory is the directory in which the files have been extracted, so it's possible to use a volume mount with a relative path to mount files or directories from the yaml file.

Example:

workload: |
 type: workload
 play:
   archive:  ${COMPOSE_VALUE}
 auths:
   us.icr.io:
     username: iamapikey
     password: Eqx0TS....
 volumes:
   test-volume:
     mount: /var/hyperprotect
     seed: workload phrase
     filesystem: ext4

• In a template format in the templates subsection of play. This section is an array of descriptors in the YAML format. Pods or ConfigMaps may have points of variability (POV) that are not known at the time of writing the descriptors. These POVs may be represented as templates and the values will be filled in at deployment time from information in the contract. We use go templates as the templating syntax, which is the same as used for helm charts, so templates can easily be exchanged with k8s. We support the following Built-In objects:

  • Environment: this object contains the environment variables as merged between the workload and the environment section. The object is available as {{ .Env }}.

  Example:

  workload: |
    type: workload
    auths:
     docker.io:
      password: <password>
      username: test
    play:
      templates:
        - apiVersion: v1
          kind: Pod
          metadata:
            name: busybox
          spec:
            containers:
            - name: main
              image: "{{ .Env.REGISTRY }}/hpse-docker-busybox-s390x@sha256:732efa374f1e6c964caeacab0bcb370385ee386041a14d4a32176462e3f75c7b"
              command:
              - printenv
              envFrom:
              - configMapRef:
                  name: contract.config.map
                  optional: false
            restartPolicy: Never
  env: |
    type: env
    logging:
      logDNA:
        ingestionKey: <ingestion Key of the Log Analysis instance>
        hostname: <host name of the Log Analysis instance>
        port: 6514
    env:
      REGISTRY: docker-io/test
  

  The {{ .Env REGISTRY }} expression references the REGISTRY environment variable that in this example is defined in the env section of the contract.

  The templates need to be valid YAML, so a replacement expression must be escaped if it appears as the first part of a string. Otherwise it collides with the block mapping syntax. This is different to helm templates where expressions are applied to the textual representation of the document instead of the model representation.

apiVersion: v1
kind: Pod
metadata:
  name: busybox
spec:
  containers:
  - name: main
    image: ...
    command:
    - printenv
    envFrom:
    - configMapRef:
        name: contract.config.map
        optional: false
  restartPolicy: Never

apiVersion: v1
kind: Pod
metadata:
  name: busybox
spec:
  containers:
  - name: main
    image: ...
    volumeMounts:
    - name: test-volume
      readOnly: true
      mountPath: /fromHost
  volumes:
  - name: test-volume
    hostPath:
      path: /var/hyperprotect
      type: Directory
  restartPolicy: Never

The images subsection

<container registry>/<username or namespace>/<image name>
eg- us.icr.io/mynamespace/my-haproxy:

notary: "https://notary.us.icr.io"

cat ~/.docker/trust/tuf/us.icr.io/<username>/<imagename>/metadata/root.json

images:
  dct:
    us.icr.io/mynamespace/my-haproxy:
      notary: "https://notary.us.icr.io"
      publicKey: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUJpRENDQVM2Z0F3SUJBZ0lSQUxCMXBPYlpEQlRRc09GSFlxazMzaWd3Q2dZSUtvWkl6ajBFQXdJd0tqRW8KTUNZR0ExVUVBeE1mZFhNdWFXTnlMbWx2TDNCeVlXSm9ZWFF4TWpNdmJYa3RhR0Z3Y205NGVUQWVGdzB5TWpBMApNVE14TURFd01ETmFGdzB6TWpBME1UQXhNREV3TUROYU1Db3hLREFtQmdOVkJBTVRIM1Z6TG1samNpNXBieTl3CmNtRmlhR0YwTVRJekwyMTVMV2hoY0hKdmVIa3dXVEFUQmdjcWhrak9QUUlCQmdncWhrak9QUU1CQndOQ0FBU1AKWGsrelE2MlFZNjI3MWQ1cTBMZHY3SGc3QzZkMGZOUlRsQmJXekhOWWFDZzlpU0piYnVNdjVBY0JmMjlqQi83eApqYzhzVitxMksyemtkTHV4QWxGWm96VXdNekFPQmdOVkhROEJBZjhFQkFNQ0JhQXdFd1lEVlIwbEJBd3dDZ1lJCkt3WUJCUVVIQXdNd0RBWURWUjBUQVFIL0JBSXdBREFLQmdncWhrak9QUVFEQWdOSUFEQkZBaUIzd0JTa0IxaXAKZHZZYlBMbFBmS3RZT0hsYnZzUllKa0FZM2hnY0xuNWhwQUloQUt6cmhsU3p4K1I5bmdtMTBlZVkyaFNCRmgrawpMWHp6SFkwaktTVzhyM1FhCi0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K

services:
  <imagename>:
    image: s390x/redis@sha256:db467ab5c53bdeef65762a7534e26fecb94a0f218bd38afd2eaba1a670c472b1

gpg -a --export ${KEY_ID}|base64 -w0

images:
  rhs:
      OCI-image-identifier:
        publicKey: abcdef

The workload - volumes subsection

The volumes section needs to be provided in the contract only if a data volume is attached to the instance at the time of creation. The information provided in this section is used to mount the attached data volume (provided by the user) and is later encrypted using the "seeds" provided in the workload and env sections. You can provide any path of your choice for the "mount" field. The path provided by the user is used internally to mount the data volume. The mount path provided in the contract must match the path provided under the volumes section of the docker-compose.yaml file, so that all the data associated with the container workload is stored in this data volume.

The volumes subsection has support for auto encryption of the data volume with user-provided seeds. If a data volume is attached to the IBM Hyper Protect Virtual Servers instance, it is encrypted automatically with the seeds that are provided through the "seed" field in the volumes subsections of the contract. Thus two seeds must be provided, one through the workload section (by the workload persona) and the other through the env section (by the deployer persona). These two seeds are internally converted to UTF8 sequences and then concatenated. Later, the hash (SHA256) of the concatenated sequence is computed as a hexdigest, which is used as the LUKS passphrase to encrypt the data volume.

You can use the following command to validate the hexdigest:

echo -n "seed1seed2" | sha256sum

Here you can learn how the 'seed' can be provided in the workload section of the contract. For more information about how the "seed" input can be provided through the env section, see The env section. It is mandatory to provide both the seeds for encryption. Encryption fails (the instance shuts down) if only one of the seeds is provided.

Note: You can add a higher level of encryption protection and control to your data at rest by integrating with Hyper Protect Crypto Services. Starting from 2.1.5, you can use Hyper Protect Crypto Services to generate a random value as the third seed and wrap it with your root key. The LUKS passphrase is generated by using three seeds - the seed in the metadata partition and the two seeds from the contract. For more information, See Securing your data.

volumes:
  test:
    filesystem: ext4
    mount: /mnt/data
    seed: workload phrase

Note: Starting from Hyper Protect Virtual Servers 2.1.4, for new instances, the data volume is partitioned into two parts. The first partition (100Mib) is reserved for internal metadata; the second partition remains as the data volume for workload. Only new volumes are partitioned, and you can't use the partitioned volume with an older version of the HPCR image. Provisioning with an existing encrypted volume also works. The difference is that the existing volume does not get partitioned, and you can also go back to an older image with this volume.

Note: Starting with IBM Hyper Protect Servers Version 2.1.6, the deployer and provider can use the "rolling of seeds" feature. An option is provided to roll or rotate the seeds to increase the security posture, or if the seed is compromised. When the deployer or the provider or both of them want to roll the seeds, the current seed information must be specified in the previousSeed parameter, and the new seed information must be specified in the seed parameter. See the snippet shown below for an example.

The following snippet is an example for the volumes section:

volumes:
  test:
    filesystem: "ext4"
    mount: "/mnt/data"
    seed: "workload phrase1"
    previousSeed: "workload phrase"

Note: Starting with IBM Hyper Protect Servers Version 2.1.7, and 2.1.6.1, you can attach multiple volumes when you bring up the virtual server instance. Volumes attached when the instance is running are ignored. Ensure that you clearly map the disk to the volumes in the contract file, and update the volume key in the contract file by using the serial parameter in the disk section of the domain.xml file. For an example, see this.

The following snippet is an example for the volumes section:

volumes:
  test1:
    filesystem: "ext4"
    mount: "/mnt/data"
    seed: "seed1"
  test2:
    filesystem: "ext4"
    mount: "/mnt/test"
    seed: "seed2"

The logging subsection

logging:
  logDNA:
    hostname: <host name of the Log Analysis instance>
    ingestionKey: <ingestion Key of the Log Analysis instance>
    port: <port default-6514>
    tags: ["custom tag name 1", "custom tag name 2"]

 env:
   logging:
     logRouter:
       hostname: <host name of the service instance> /
       iamApiKey: <iamApiKey of the service instance> / xxxx
       port: <port of the service instance(443)>

The env - volumes subsection

Read the workload - volumes subsection of the workload section before you continue with this section. As already mentioned, for auto disk encryption of the attached data volume, you must provide two customer seeds, one in the workload - volumes subsection, and the other in the env- volumes subsection. The seeds can be any random text of your choice.

This is an example of the env - volumes subsection:

volumes:
  test:
    seed: env phrase

The following snippet as an example when you use the "rolling of seeds" feature:

volumes:
  test:
    seed: env phrase1
    previousSeed: env phrase

The following snippet is an example when you use multiple volumes:

env:
  logging:
    logDNA:
      hostname: syslog-a.eu-gb.logging.cloud.ibm.com
      ingestionKey: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
      port: 6514
  volumes:
    test1:
      seed: "seed1"
    test2:
      seed: "seed2"

Note: The key of the volume must be the same as that in the workload - volumes subsection.

As mentioned, you can integrate with Hyper Protect Crypto Services to generate a third seed and wrap it with your root key. See the following example. For more information, See Securing your data.

volumes:
 test:
   kms:
     - apiKey: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
       crn: "crn:v1:bluemix:public:hs-crypto:us-south:a/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
       type: "public"
     - apiKey: "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
       crn: "crn:v1:bluemix:public:hs-crypto:us-south:a/xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx:key:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
       type: "private"
   seed: "seed1"
   kmsTimeout: 10

signingKey subsection

For information about how to use the signingKey, see Contract signature.

env subsection

• If Pod descriptors are used in the workload section:

  See the example for the template format in the play subsection.

• If a docker compose file is used in the workload section:

  If the docker compose file has an environment section, you can use the following snippet as an example:

  environment:
    KEY1: "${Value1}"
    KEY2: "${Value2}"
  

  When the docker compose file has an environment section, as shown in the example above, then you can pass the values in the env section of the deployer. The following example shows how to specify the values for the env variables:

  env:
   value1: "abc"
   value2: "xyz"
  

Downloading the encryption certificate and extracting the public key

1. Get the certificate that is used to encrypt the contract from the image TAR file.
2. Validate the encryption certificate by following the instructions here.

Creating the encrypted workload section of a contract

The value of any section in a contract can be in plain text or encrypted. Complete the following steps to encrypt the workload section used in a contract:

1. Create the docker-compose.yaml file based on your workload requirements. For example,

   services:
     redisnode01:
       image: s390x/redis@sha256:db467ab5c53bdeef65762a7534e26fecb94a0f218bd38afd2eaba1a670c472b1
       ports:
         - "6379:6379"
   

   For more information, see Overview of Docker Compose.

2. Create the workload section of the contract and add the contents in the workload.yaml file.

3. Export the complete path of the workload.yaml file and ibm-hyper-protect-container-runtime-24.9.1-encrypt.crt:

   WORKLOAD="<PATH to workload.yaml>"
   CONTRACT_KEY="<PATH to ibm-hyper-protect-container-runtime-24.9.1-encrypt.crt>"
   

4. Use the following command to create a random password (the contract is encrypted via symmetric AES with a random PASSWORD):

   PASSWORD="$(openssl rand 32 | base64 -w0)"
   

5. Use the following command to encrypt password with ibm-hyper-protect-container-runtime-24.9.1-encrypt.crt:

   ENCRYPTED_PASSWORD="$(echo -n "$PASSWORD" | base64 -d | openssl rsautl -encrypt -inkey $CONTRACT_KEY -certin | base64 -w0 )"
   

6. Use the following command to encrypt the workload.yaml file with a random password:

   ENCRYPTED_WORKLOAD="$(echo -n "$PASSWORD" | base64 -d | openssl enc -aes-256-cbc -pbkdf2 -pass stdin -in "$WORKLOAD" | base64 -w0)"
   

7. Use the following command to get the encrypted section of the contract:

   echo "hyper-protect-basic.${ENCRYPTED_PASSWORD}.${ENCRYPTED_WORKLOAD}"
   

8. Get the output from step 7 and add it to the user-data.yaml file.

   workload: hyper-protect-basic.js7TGt77EQ5bgTIKk5C0pViFTRHqWtn..............
   

   Note: The prefix hyper-protect-basic is mandatory.

Creating encrypted env section of a contract

Complete the following steps to encrypt the env section used in a contract:

1. Create the env section of the contract and add the contents in the env.yaml file.

2. Export the complete path of the env.yaml file and ibm-hyper-protect-container-runtime-24.9.1-encrypt.crt:

   ENV="<PATH to env.yaml>"
   CONTRACT_KEY="<PATH to ibm-hyper-protect-container-runtime-24.9.1-encrypt.crt>"
   

3. Use the following command to create a random password:

   PASSWORD="$(openssl rand 32 | base64 -w0)"
   

4. Use the following command to encrypt password with ibm-hyper-protect-container-runtime-24.9.1-encrypt.crt:

   ENCRYPTED_PASSWORD="$(echo -n "$PASSWORD" | base64 -d | openssl rsautl -encrypt -inkey $CONTRACT_KEY  -certin | base64 -w0)"
   

5. Use the following command to encrypt env.yaml with a random password:

   ENCRYPTED_ENV="$(echo -n "$PASSWORD" | base64 -d | openssl enc -aes-256-cbc -pbkdf2 -pass stdin -in "$ENV" | base64 -w0)"
   

6. Use the following command to get the encrypted section of the contract:

   echo "hyper-protect-basic.${ENCRYPTED_PASSWORD}.${ENCRYPTED_ENV}"
   

7. To encrypt the workload section, see Creating the encrypted workload section of a contract.

8. Get the output from step 6 and add it to the user-data.yaml file.

   env: hyper-protect-basic.VWg/5/SWE+9jLfhr8q4i.........
   

1. Get the details of your logging instance

You can configure logging with IBM Log Analysis or a generic syslog backend. This example uses IBM Log Analysis. There are different plans that you can choose from. To understand how you get the required details including the hostname and the ingestion key, see Logging for IBM Hyper Protect Virtual Servers.

2. Create the env section

Ensure that you do not miss the pipe symbol '|' if you are using a plain text contract. It is not required if you are planning to encrypt the section.

env: |
  type: env
  logging:
    logDNA:
      hostname: syslog-a.au-syd.logging.cloud.ibm.com
      ingestionKey: XXXXXXXXXX
      port: 6514

3. Prepare the docker-compose file

Assuming that you have the logging details, find a simple docker compose file. The following example has a public NGINX container. Create a docker-compose.yaml by using the example.

services:
  nginx:
    image: docker.io/library/nginx@sha256:b1306efee704017b0e02efadc011d374063a4e9c47b86bdc57744fc3f0666383
    ports:
    - 80:80
    - 443:443

4. Get the base64 encoded version of the docker-compose file

tar -czvf compose.tgz docker-compose.yaml

base64 -i compose.tgz > compose.b64

5. Create the compose section with it

  compose:
    archive: H4sIADXNg2IAA+3W326CMBQGcK59it555XbanraMq70KlOLIJhjqzPb2q6g3S9xiIi7T75eQlj+hDYcP6vvVuo/hMZsQJc6YsU2+t2NfsmKyyhHLjKRUSmbCTDmpo/e4KQchsqHvNz9d99v5f8of6l/3/jUMi8Puw+fq7XJj7ApsmU/WX2m7r7/j9Abs6s/W2kzQ5aZw2p3XfxuG2PZdIeZ6Poth2LY+xGImRLdsu49dR4h2VS5DsT/yHF9KZWxRSU02NCGkxJJ0FQVSoSlrn8Jba5eyrEsOT55dlduq9sY55sbrhlJpda7HG6/7YRP3YyxETkVOhz6zLtI2++unc/tO5b+84AfgrPyn4JM0pDXyfw3I/32bMvdH5+SfOK0TpdZWIv/XgPzftynX/Udn/f/NmH+l8P+/CuQfAAAAAAAAAAAAAOD2fAEPQbuiACgAAA==

6. Populate the workload section. Ensure that you do not miss the pipe symbol (|) if you are using a plain text contract

workload: |
  type: workload
  compose:
    archive: H4sIADXNg2IAA+3W326CMBQGcK59it555XbanraMq70KlOLIJhjqzPb2q6g3S9xiIi7T75eQlj+hDYcP6vvVuo/hMZsQJc6YsU2+t2NfsmKyyhHLjKRUSmbCTDmpo/e4KQchsqHvNz9d99v5f8of6l/3/jUMi8Puw+fq7XJj7ApsmU/WX2m7r7/j9Abs6s/W2kzQ5aZw2p3XfxuG2PZdIeZ6Poth2LY+xGImRLdsu49dR4h2VS5DsT/yHF9KZWxRSU02NCGkxJJ0FQVSoSlrn8Jba5eyrEsOT55dlduq9sY55sbrhlJpda7HG6/7YRP3YyxETkVOhz6zLtI2++unc/tO5b+84AfgrPyn4JM0pDXyfw3I/32bMvdH5+SfOK0TpdZWIv/XgPzftynX/Udn/f/NmH+l8P+/CuQfAAAAAAAAAAAAAOD2fAEPQbuiACgAAA==

7. Your simple contract is ready

env: |
  type: env
  logging:
    logDNA:
      hostname: syslog-a.au-syd.logging.cloud.ibm.com
      ingestionKey: xxxxxxxxxx
      port: 6514
workload: |
  type: workload
  compose:
    archive: H4sIADXNg2IAA+3W326CMBQGcK59it555XbanraMq70KlOLIJhjqzPb2q6g3S9xiIi7T75eQlj+hDYcP6vvVuo/hMZsQJc6YsU2+t2NfsmKyyhHLjKRUSmbCTDmpo/e4KQchsqHvNz9d99v5f8of6l/3/jUMi8Puw+fq7XJj7ApsmU/WX2m7r7/j9Abs6s/W2kzQ5aZw2p3XfxuG2PZdIeZ6Poth2LY+xGImRLdsu49dR4h2VS5DsT/yHF9KZWxRSU02NCGkxJJ0FQVSoSlrn8Jba5eyrEsOT55dlduq9sY55sbrhlJpda7HG6/7YRP3YyxETkVOhz6zLtI2++unc/tO5b+84AfgrPyn4JM0pDXyfw3I/32bMvdH5+SfOK0TpdZWIv/XgPzftynX/Udn/f/NmH+l8P+/CuQfAAAAAAAAAAAAAOD2fAEPQbuiACgAAA==