Building your application with the Secure Build virtual server (SBS)

Creating the certificate and key to securely communicate with secure build server

1. Run the following command.

   cd $HOME/hpvs/config/securebuild/keys
   

2. Create the certificate and key to securely communicate with secure build server.

   openssl req -newkey rsa:2048 \
   -new -nodes -x509 \
   -days 3650 \
   -out sbs.cert \
   -keyout sbs.key \
   -subj "/C=GB/O=IBM/CN=johndoe.example.com"
   

   Note: If you see errors like random number generator:RAND_load_file:Cannot open file, then run the following commands.

   openssl rand -out $HOME/.rnd -hex 256
   

3. Run the following command to change the certificate to base64 encoding.

   echo $(cat sbs.cert | base64) | tr -d ' ' >> sbs_base64.cert
   

After the key is generated, ensure that you keep the key safe, to prevent inadvertent security issues.

Creating OpenSSL certificates

For IBM Hyper Protect Virtual Servers version 1.2.6, or later, complete the following steps to generate CA signed certificate and keygen.

1. Generate certificates for secure communication between the between the client and server. For more information on generating the certificates, see Creating OpenSSL certificates for Secure Build virtual server.

2. Run the following command to change the certificate to base64 encoding.

   echo $(cat ~/hpvs/config/securebuild/keys/ca.pem | base64) | tr -d ' ' >> clientca_base64.cert
   echo $(cat ~/hpvs/config/securebuild/keys/client_cert.pem | base64) | tr -d ' ' >> client_base64.cert
   echo $(cat ~/hpvs/config/securebuild/keys/server.pem | base64) | tr -d ' ' >> server_base64.cert
   echo $(cat ~/hpvs/config/securebuild/keys/server-key.pem | base64) | tr -d ' ' >> server_base64.key
   

After the key is generated, ensure that you keep the key safe, to prevent inadvertent security issues.

Create virtual server by using the yaml configuration file and hpvs deploy command

This is the recommended option to provision the instance because of it's ease of use and is also an easier method of creating multiple instances quickly.

1. Update the template file $HOME/hpvs/config/templates/virtualserver.template.yml based on the networking configuration, quotagroup and resource settings of the Hyper Protect Virtual Server instance if necessary. The vs_securebuild.yml that has the configuration details for the virtual server refers to the corresponding sections of the virtualserver.template.yml when you run the hpvs deploy command. For example, the resourcedefinition: ref value refers to the resourcedefinitiontemplate definition in the template file. The network: ref value refers to the networktemplates definition in the template file.

   version: v1
   type: virtualserver-template
   networktemplates:
   - name: external_network
     subnet: "10.20.4.0/22"
     gateway: "10.20.4.1"
     parent: "encf900"
     driver: "macvlan"
   - name: internal_network
     subnet: "192.168.40.0/24"
     gateway: "192.168.40.1"
     parent: "encf900"
     driver: "bridge"
   quotagrouptemplates:
   # Passthrough quotagroup templates - A quotagroup will be dynamically created based
   # on the template and attached as single volume mount point to the virtual server.
   # Allowed filesystem types for the passthrough type quogagroup are btrfs, ext4, xfs
   - name: p-small
     size: 20GB
     filesystem : ext4
     passthrough: true
   - name: p-medium
     size: 50GB
     filesystem : ext4
     passthrough: true
   - name: p-large
     size: 100GB
     filesystem : ext4
     passthrough: true
   - name: p-xlarge
     size: 200GB
     filesystem : ext4
     passthrough: true
   - name: p-xxlarge
     size: 400GB
     filesystem : ext4
     passthrough: true
   # Non passthrough quotagroup definitions - This quotagroups can be shared by
   # creating multiple volume mountpoints with the same virtual server or multiple
   # virtual server.  A non passthrough quotagroup will be dynamically created based
   # on the template and attached as volume mount points to the virtual server.
   # Only brtfs filesystem is supported in non passthrough quotagroups
   # mount points attached to virtual server can have filesystem btrfs, ext4, xfs
   - name: np-small
     size: 20GB
     passthrough: false
   - name: np-medium
     size: 50GB
     passthrough: false
   - name: np-large
     size: 100GB
     passthrough: false
   - name: np-xlarge
     size: 200GB
     passthrough: false
   - name: np-xxlarge
     size: 400GB
     passthrough: false
   resourcedefinitiontemplates:
   - name: default
     cpu: 1
     memory: 1024
   - name: small
     cpu: 2
     memory: 2048
   - name: large
     cpu: 4
     memory: 4096
   - name: xl
     cpu: 8
     memory: 8192
   - name: xxl
     cpu: 12
     memory: 12288
   

   For more information about the template file for a Hyper Protect Virtual Server instance, see Virtual server template file.

2. Create the configuration yaml file $HOME/hpvs/config/securebuild/demo_securebuild.yml for the instance by referring to the example file $HOME/hpvs/config/securebuild/vs_securebuild.yml. The following is an example of a vs_securebuild.yml file. In this example, the network definition is for an external network. For more information on other network configurations, see Network requirements for Hyper Protect Virtual Server. For more information about quotagroups in IBM Hyper Protect Virtual Servers, see Overview of quotagroups for IBM Hyper Protect Virtual Servers.

   version: v1
   type: virtualserver
   virtualservers:
   - name: securebuildserver
     host: SSC_LPAR_NAME
     repoid: SecureDockerBuild
     imagetag: 1.2.7.9
     imagefile: SecureDockerBuild.tar.gz
     imagecache: true
     resourcedefinition:
        ref: small
     environment:
      - key: ROOTFS_LOCK
        value: "y"
      - key: CLIENT_CRT
        value: "@/root/hpvs/config/securebuild/keys/client_base64.cert" # provide certificate file in base64 format
      - key: CLIENT_CA
        value: "@/root/hpvs/config/securebuild/keys/clientca_base64.cert" # provide certificate file in base64 format
      - key: SERVER_CRT
        value: "@/root/hpvs/config/securebuild/keys/server_base64.cert" # provide certificate file in base64 format
      - key: SERVER_KEY
        value: "@/root/hpvs/config/securebuild/keys/server_base64.key" # provide key file in base64 format
      - key: RUNQ_ROOTDISK
        value: newroot
     networks:
      - ref:  external_network
        ipaddress: 10.20.4.67
     volumes:
      - name: securebuild_qg
        ref: np-medium
        mounts:
         - mountpoint: /data
           filesystem: ext4
           size: 16GB
           mount_id: data
         - mountpoint: /docker
           filesystem: ext4
           size: 16GB
           mount_id: docker
         - mountpoint: /newroot
           filesystem: ext4
           size: 10GB
           mount_id: newroot
           reset_root: false
   

   For more information about the config file for a Hyper Protect Virtual Server instance, see Virtual Server Configuration file. Note: You must configure the mount point as /newroot when you deploy an image that is based on the base image.

3. Create the instance by using the configurations in the yaml file.

   hpvs deploy --config $HOME/hpvs/config/securebuild/demo_securebuild.yml
   

   Note:

   • You can use the hpvs undeploy command to delete this virtual server. For more information, see Undeploying virtual servers.
   • You can update the resources or configuration of a virtual server after the completion of the deploy operation by using the -u, or the --update flag of the hpvs deploy command. For more information, see Updating virtual servers.

Create virtual server by using the hpvs image and hpvs vs create commands

1. Upload the Secure Build image SecureDockerBuild.tar.gz to the Secure Service Container partition.

   hpvs image load --file=$HOME/hpvs/config/securebuild/images/SecureDockerBuild.tar.gz
   

2. Export the certificate as an environment variable. For IBM Hyper Protect Virtual Servers version 1.2.5, or earlier, run the following command:

   export cert=$(echo $(cat ~/hpvs/config/securebuild/keys/sbs.cert | base64) | tr -d ' ')
   

   For IBM Hyper Protect Virtual Servers version 1.2.6, or later, run the following commands:

   export ca_cert=$(echo $(cat ~/hpvs/config/securebuild/keys/ca.pem | base64) | tr -d ' ')
   export client_cert=$(echo $(cat ~/hpvs/config/securebuild/keys/client_cert.pem | base64) | tr -d ' ')
   export server_cert=$(echo $(cat ~/hpvs/config/securebuild/keys/server.pem | base64) | tr -d ' ')
   export server_key=$(echo $(cat ~/hpvs/config/securebuild/keys/server-key.pem | base64) | tr -d ' ')
   

3. Create the quotagroup for the Secure Build virtual server.

   hpvs quotagroup create --name securebuild_qg --size=50GB
   

   Note: If you create a non-passthrough quotagroup for the Secure Build virtual server, it is recommended that you ensure that 20% of disk space is always available in order to address any I/O errors. For more information about the hpvs quotagroup command, see Commands in IBM Hyper Protect Virtual Servers. For more information about quotagroups in IBM Hyper Protect Virtual Servers, see Overview of quotagroups for IBM Hyper Protect Virtual Servers.

4. Create the external network for the Secure Build virtual server.

   hpvs network create --name external_net --driver macvlan --parent encf900 --subnet 10.20.4.0/22 --gateway 10.20.4.1
   

   For more information about the hpvs network command, see Commands in IBM Hyper Protect Virtual Servers. For more information about the network in IBM Hyper Protect Virtual Servers, see Network requirements for Hyper Protect Virtual Server.

5. Create the Secure Build virtual server.

   hpvs vs create --name securebuildserver --repo SecureDockerBuild \
   --tag 1.2.7.9 --cpu 2 --ram 2048 --env={EX_VOLUMES="/docker,/data",ROOTFS_LOCK=y,CLIENT_CRT=$client_cert,CLIENT_CA=$ca_cert,SERVER_CRT=$server_cert,SERVER_KEY=$server_key,RUNQ_ROOTDISK=new} \
   --quotagroup "{quotagroup = securebuild_qg, mountid = new, mount = /newroot, filesystem = ext4, size = 4GB,  reset_root=true}" \
   --quotagroup "{quotagroup = securebuild_qg, mountid = data, mount = /data, filesystem = ext4, size = 4GB}" \
   --quotagroup "{quotagroup = securebuild_qg, mountid = docker, mount = /docker, filesystem = ext4, size = 16GB}" \
   --network "{name = external_net,ip = 10.20.4.12}"
   

   where

   • /newroot storage on the quotagroup securebuild_qg is for the Secure Build server image. You must configure the mount point as /newroot when you deploy an image that is based on the base image.
   • /data storage on the quotagroup securebuild_qg is for the log configuration date.
   • /docker storage on the qutogroup securebuild_qg is for the applications to be built on the Secure Build server.
   • CLIENT_CRT, CLIENT_CA, SERVER_CRT, SERVER_KEY is to ensure only authorized REST API calls from the Secure Build virtual server can be accepted by the hosting appliance in order to build Hyper Protect Virtual Server instances.
   • For a full list of supported parameters and options of the hpvs command, see Commands in IBM Hyper Protect Virtual Servers.
   • In this example, the network definition is for an external network. For more information on other network configurations, see Network requirements for Hyper Protect Virtual Server.
   • For more information about quotagroups in IBM Hyper Protect Virtual Servers, see Overview of quotagroups for IBM Hyper Protect Virtual Servers.

   Note: You can update the resources or configuration of a virtual server after the virtual server is created by using the hpvs vs update command. For more information, see Updating Hyper Protect Virtual Server containers.

Generating the signing keys

To generate the signing keys, follow the instructions listed in Generating the signing keys.

Building the application by using the Secure Build

1. Create the Secure Build configuration file. You can use the $HOME/hpvs/config/securebuild/secure_build.yml.example example file as a reference when updating the file.

   secure_build_workers:
     sbs:
        url: '<url of the secure build service. e.g- https://test.abc.net>'
        port: '443'
        cert_path: '<complete path of certificate.  e.g- /root/hpvs/config/securebuild/keys/client_cert>'
        key_path: '<complete path of key.  e.g- /root/hpvs/config/securebuild/keys/client_key>'
        ca_cert_path: '<complete path of ca_certificate.  e.g- /root/hpvs/config/securebuild/keys/ca_cert>'
     regfile:
        id: '<Enter Id. It could be any name>'
     github:
        url: '<git hub url. e.g- git@github.com:MyOrg/my-docker-app.git>'
        branch: 'master'
        ssh_private_key_path: '<complete path of key github private key. e.g - /root/git_key>'
        recurse_submodules: 'False'
        dockerfile_path: './Dockerfile'
        docker_build_path: '<Enter the path to the subdirectory within the Github project to be used as the build context for the Docker build>'
     docker:
        push_server: '<get this from hpvs registry list. e.g - docker_push>'
        base_server: '<get this from hpvs registry list. e.g - docker_base>'
        pull_server: '<get this from hpvs registry list. e.g - docker_pull>'
        repo: 'docker_user_name/docker_image_name'
        image_tag_prefix: 'latest'
        content_trust_base: 'True'
        icr_base_repo: '<provide the icr base image used in dockerfile. e.g - us.icr.io/sbswork/sbs:latest>'
        base_repo_public_key_path: '<provide the public key that was used to sign the icr base image. e.g - /root/hpvs/config/securebuild/keys/icrsign.pub>'
     manifest_cos:
        bucket_name: '<Enter the bucket name on the S3 object store where manifest files will be transferred to after each build>'
        api_key: '<Enter the API key used to authenticate with the S3 object store>'
        resource_crn: '<Enter the resource instance ID for the S3 object store>'
        auth_endpoint: '<Enter the authentication endpoint for the S3 object store>' (For example: `https://iam.cloud.ibm.com/identity/token`)
        endpoint: '<Enter the endpoint for the S3 object store>' (For example:'https://s3.us-east.cloud-object-storage.appdomain.cloud')
     # Add all allowlist environment variables that are required in your virtual server. If you try to create a virtual server with environment variables that are not added to the allowlist, then creating the virtual server fails. This is an optional parameter and if you do not have any environment variable for the virtual server, you can comment this parameter.
     env:
        allowlist: [KEY1,KEY2]
     build:
        args:
          <ARG1>: '<value1>'
          <ARG2>: '<value2>'
     signing_key:
        private_key_path: '<Enter the absolute private key path. For example, /root/hpvs/config/securebuild/keys/isv_user.private'
        public_key_path: '<Enter the absolute public key path. For example, /root/hpvs/config/securebuild/keys/isv_user.pub'
     isv_secrets:
           secrets_list:
              - key1: value1
              - key2: value2
     # Add linux capabilities to hyper protect virtual server.
     # List of Linux capabilities are available here https://man7.org/linux/man-pages/man7/capabilities.7.html.
     # All the capabilities listed are supported except "CAP_PERFMON", "CAP_BPF", and CAP_CHECKPOINT_RESTORE".
     # While adding capabilities remove the prefix "CAP".
     # For example CAP_AUDIT_CONTROL will be AUDIT_CONTROL
     cap_add: [] # eg: ["NET_ADMIN","NET_RAW"], or ["ALL"]
   

   Note:

   • If the Dockerfile for the image requires multiple ‘FROM’ statements to load different Docker images, ensure that they are all signed by using Red Hat signing only, if they use ICR.
   • If the image is signed by Docker Content Trust and is present in ICR, then the verification of it's signature is not supported.
   • When you are using Red Hat signed images from ICR, and content_trust_base is set to True, then you have to provide the public key of the signature (base_repo_public_key_path), and the name of the base repository (icr_base_repo) that you are using. If base image is not Red Hat signed, then these two parameters must be commented. For more information, see Signing images for trusted content.
   • IBM Hyper Protect Virtual Servers version 1.2.7, or later, supports pulling SUSE images from the SUSE registry. Ensure that you comment the base_server parameter, and set the content_trust_base parameter value as False.
   • The --isv_secrets parameter is optional and is supported with IBM Hyper Protect Servers version 1.2.7, or later. When the ISV needs any secrets to be passed for use by the HPVS workloads, use the --isv_secrets parameter. The ISV secrets is a key value pair that is separated by a colon, and you can specify a list secrets that are separated by a comma. Avoid adding spaces after the comma when you are specifying multiple secrets. The secrets are added in the /isv_secrets/secrets.json file within the IBM Hyper Protect Virtual server. The contents of the /isv_secrets/secrets.json file is {"key1": "value1", "key2": "value2"}.
   • If the base image in Dockerfile is not signed then the base_server parameter is not required and content_trust_base must be False. This also applies to SUSE registry because Docker credentials are not required.
   • If you want to specify a non-default SSH port, then you can add the value of the port that you want to use in the github url parameter as shown above in the secure_build.yml.example file. When no port is specified, the github url can be specified as "git@github.com:MyOrg/my-docker-app.git".
   • To enable all privileges you can use cap_add:["ALL"], but as a good security practice, provide the least possible privileges to your virtual server.
   • Build parameters (build args) are used to give additional information as might be required for the specific application that you want to run on the virtual server.
   • You must provide valid GitHub URL and also ensure that you use a .git extension when specifying the URL.
   • It is recommended that you choose an endpoint URL that is located in the same region as your service or application, and specify this URL as the value for the endpoint parameter in the manifest_cos section of the secure_build.yml file. For more information about identifying endpoint URL, see Cloud Object Storage.

   For a full list of supported parameters in the configuration file, see Secure Build configuration file.

   To configure a Cloud Object Storage service to archive the application manifest files of your applications built by your Secure Build container, ensure that you have the following information about your IBM Cloud Object Storage at hand.

   • The API Key to the cloud object storage service
   • The object storage bucket to store the manifest
   • The resource instance name of the cloud object storage service
   • The authentication endpoint for the cloud object storage service
   • The endpoint for the cloud object storage service

2. Build your application and upload the application manifest file to the cloud object storage by using Secure Build. You can choose either of the following options:

   • Use one command to perform all the Secure Build actions including initialization, build, and generating the encrypted repository registration file. This option is recommended if you are building the application by using the Secure Build for the first time.

     Note: You must map the Secure Build Server IP with the Subject Alternative Name, before you run the hpvs sb init command. For example:

     10.20.4.2 test.abc.com
     

     hpvs sb init --config $HOME/hpvs/config/securebuild/secure_build.yml.example --out $HOME/hpvs/config/MyDockerAppImageRegfile.enc --build
     

   • Use individual commands to perform each step of building the application by using the Secure Build virtual server. This option is recommended if you plan to build the application by using the Secure Build multiple times. In this scenario, you can run the hpvs sb build command for subsequent builds. The --isvsecret parameter is optional and is applicable for IBM Hyper Protect Servers version 1.2.7, or later.

     hpvs sb build --config $HOME/hpvs/config/securebuild/secure_build.yml.example
     hpvs sb regfile --config $HOME/hpvs/config/securebuild/secure_build.yml.example --isvsecret --out $HOME/hpvs/config/MyDockerAppImageRegfile.enc
     

   You can log in to your cloud account and check the application manifest file has been transferred to its bucket in your Cloud Object Storage service after the commands complete execution.

   You can use the hpvs sb manifest command to download the manifest file of the secure build.

   hpvs sb manifest --config $HOME/hpvs/config/securebuild/secure_build.yml.example --name <build_name>
   

   where you can get the <build_name> by using the hpvs sb status after the build completes. When the command execution completes, the manifest file is downloaded to the current directory from which the hpvs sb manifest command was run from. To verify the signature of the manifest file, see instructions in Verifying the signature of the manifest file.

   Note:

   • If the hpvs sb init, hpvs sb build, or the hpvs sb regfile commands fails for any reason, for example you specified incorrect parameters, then you can use the hpvs sb update command to update the configuration of the Secure Build configuration and rerun the commands with the updated configuration. The regfile[id] and docker[repo] parameters cannot be updated by using this command.
   • You can use the hpvs sb log command to view the run time logs of the secure build process, or for troubleshooting or debugging. The logs are available when you run the hpvs sb init, hpvs sb build, or the hpvs sb regfile commands.
   • You can use the hpvs sb status command to view the status of the last secure build process.
   • You can use the hpvs sb clean command to clean the logs of the secure build process. Build artifacts from the earlier builds are deleted.
   • For more information about the secure build commands, see hpvs sb.

Deploying the application by using the yaml configuration file and hpvs deploy command

1. Create the configuration yaml file $HOME/hpvs/config/demo_app.yml for the instance by referring to the example file $HOME/hpvs/config/vs_regfiledeployexample.yml. The following is an example of a vs_regfiledeployexample.yml file.

   version: v1
   type: virtualserver
   virtualservers:
   - name: testcontainer
     host: SSC_LPAR_NAME
     repoid: MyDockerRepo
     imagetag: latest
     reporegfile: /HOME/hpvs/config/MyDockerAppImageRegfile.enc
     imagecache: true
     resourcedefinition:
        ref: small
     networks:
      - ref:  external_network
        ipaddress: 10.20.4.61
     volumes:
      - name: myquotagroup
        ref : np-medium
        mounts:
         - mount_id: new
           mountpoint: /new
           filesystem: ext4
           size: 10GB
   

   In this example, the network definition is for an external network. For more information on other network configurations, see Network requirements for Hyper Protect Virtual Server. For more information about quotagroups in IBM Hyper Protect Virtual Servers, see Overview of quotagroups for IBM Hyper Protect Virtual Servers. For more information about the config file for a Hyper Protect Virtual Server instance, see Virtual server Configuration file.

2. Deploy the image by using the configurations in the yaml file.

   hpvs deploy --config $HOME/hpvs/config/demo_app.yml
   

   Note:

   • You can use the hpvs undeploy command to delete this virtual server. For more information, see Undeploying virtual servers.
   • You can update the resources or configuration of a virtual server after the completion of the deploy operation by using the -u, or the --update flag of the hpvs deploy command. For more information, see Updating virtual servers.

Deploying the application by using the hpvs vs create command

1. Register the repository on the Secure Service Container partition for the application image by using the generated repository registration file.

   hpvs repository register --pgp=$HOME/hpvs/config/MyDockerAppImageRegfile.enc --id=MyDockerRepo
   

2. Create the quotagroup of the application image on the Secure Service Container partition.

   hpvs quotagroup create --name myquotagroup --size=30GB
   

   Note: If you create a non-passthrough quotagroup for the Secure Build virtual server, it is recommended that you ensure that 20% of disk space is always available in order to address any I/O errors.

3. Deploy the application image into the IBM Hyper Protect Virtual Servers as a Hyper Protect Virtual Server instance.

   hpvs vs create --name testcontainer --repo MyDockerRepo --tag latest --cpu 2 --ram 2048 --env={env_var1=value1,env_var2=value2} --quotagroup "{quotagroup = myquotagroup, mountid = new, mount = /newroot, filesystem = btrfs, size = 25GB}" --network "{name = external_net,ip = 10.20.4.73}"