Creating the Hyper Protect Secure Build Server configuration

Create the sbs-config.json file in your current working directory, for example, the secure-build-cli directory. And then add the following content into the file:

{
  "HOSTNAME": "sbs.example.com",
  "CICD_PORT": "443",
  "IMAGE_TAG": "",
  "CONTAINER_NAME": "SBContainer",
  "RUNTIME_TYPE": "on-prem",
  "GITHUB_KEY_FILE": "~/.ssh/id_rsa",
  "GITHUB_URL": "git@github.com:<git_user>/<git_repo>.git",
  "GITHUB_BRANCH": "main",
  "DOCKER_REPO": "<docker_namespace>/<docker_repository_name>",
  "DOCKER_USER": "<docker_user>",
  "DOCKER_PASSWORD": "<docker_password>",
  "IMAGE_TAG_PREFIX": "<docker_image_tag>",
  "DOCKER_CONTENT_TRUST_BASE": "False",
  "DOCKER_CONTENT_TRUST_BASE_SERVER": "",
  "DOCKER_RO_USER": "<docker_user>",
  "DOCKER_RO_PASSWORD": "<docker_password>",
  "DOCKER_BASE_USER": "",
  "DOCKER_BASE_PASSWORD": "",
  "ICR_BASE_REPO": "",
  "ICR_BASE_REPO_PUBLIC_KEY": "",
  "ENV_WHITELIST":  ["<KEY1>", "<KEY2>"],
  "ARG": {
    "<BUILD_ARG1>": "<VALUE1>",
    "<BUILD_ARG2>": "<VALUE2>"
  }
}

Where:

  • HOSTNAME - The hostname of the HPSB server which will be used while generating certificates and communicating with the secure build server.
  • RUNTIME_TYPE - Set to on-prem to leverage IBM Hyper Protect Virtual Servers.
  • CICD_PORT - The port on which a build service is running (default: 443).
  • IMAGE_TAG - The container image tag to be deployed as the HPSB server. Use 1.3.0.14 unless otherwise noted.
  • CONTAINER_NAME - The name of the HPSB instance that you want to create on VPC. This name can be different from the name that you use on VPC. The name is used as a part of a certificate file name. You can choose any valid string as a file name.
  • GITHUB_KEY_FILE - The private key path to access your GitHub repo.
  • GITHUB_URL - The GitHub repo of the source code repo.
  • GITHUB_BRANCH - The GitHub branch name of the source code repo.
  • DOCKER_REPO - The DockerHub repository to store the built image.
  • DOCKER_USER - The docker user name with the write access to the repository.
  • DOCKER_PASSWORD - The docker password with the write access to the repository.
  • IMAGE_TAG_PREFIX - The prefix of the image tag for the image to be built. The full image tag will be IMAGE_TAG_PREFIX + '-' + the leading seven digits from the GitHub repository hash.
  • DOCKER_CONTENT_TRUST_BASE - If your base image that mentioned in the Dockerfile is signed, then set it true.
  • DOCKER_CONTENT_TRUST_BASE_SERVER - If your base image mentioned in the Dockerfile is signed, then you can specify the notary URL. The default value is https://notary.docker.io.
  • DOCKER_BASE_USER - The docker user name of repository that has the the base image.
  • DOCKER_BASE_PASSWORD - The docker password of repository that has base image.
  • DOCKER_RO_USER - You can use the same value as the DOCKER_USER. It is recommended that you specify a user who has the read access only to your Docker repository.
  • DOCKER_RO_PASSWORD - You can use the same value as the DOCKER_PASSWORD. It is recommended that you specify a user who has the read access only to your Docker repository.
  • ENV_WHITELIST - All environment variable names need to be listed. The Hyper Protect Virtual Servers only accept the environment variables in this list because of the security reasons.
  • ARG - You have to pass all build argument parameters in this parameter during the Docker build.
  • ICR_BASE_REPO - The base Image used in the dockerfile if it is present in IBM Cloud Registry (ICR).
  • ICR_BASE_REPO_PUBLIC_KEY - The public key with which the base image specified in the ICR_BASE_REPO is signed.

Note:

  1. If you use IBM Cloud Registry instead of DockerHub registry, then you must use the following parameters:

    "DOCKER_BASE_SERVER": "<domain_name>",
    "DOCKER_PUSH_SERVER": "<domain_name>",
    "DOCKER_USER": "iamapikey",
    "DOCKER_PASSWORD": "<ibm_cloud_apikey>"
    "DOCKER_RO_USER": "iamapikey",
    "DOCKER_RO_PASSWORD": "<ibm_cloud_apikey>",
    "DOCKER_CONTENT_TRUST_PUSH_SERVER": "https://<domain_name>"
    

    Where:

    • The <domain_name> specifies the location of IBM Cloud Container Registry such as us.icr.io. Select the domain name for one of available regions.
    • If you are using the IBM Cloud Registry server, and you specified the <domain_name> as us.icr.io, then specify us.icr.io as the value for DOCKER_CONTENT_TRUST_PUSH_SERVER. As another example, if the value of DOCKER_REPO is de.icr.io, then the value of DOCKER_CONTENT_TRUST_PUSH_SERVER should be de.icr.io. For more information about IBM Cloud registry, see Getting started with IBM Cloud Container Registry.
  2. If the base image is on IBM Cloud Container Registry, you must configure the DOCKER_BASE_USER and DOCKER_BASE_PASSWORD parameters. Note that only Red Hat single sign (RHSS) is supported.

  3. If the base image is on Docker Hub and is private, you must configure the DOCKER_BASE_USER and DOCKER_BASE_PASSWORD parameters. Otherwise, you don't have to set the "DOCKER_BASE_USER" and "DOCKER_BASE_PASSWORD" parameters.

  4. If the base image used in the dockerfile is signed, configure DOCKER_CONTENT_TRUST_BASE to True. And configure DOCKER_BASE_USER and DOCKER_BASE_PASSWORD with the credentials.

  5. If the base image is on IBM Cloud Container Registry and Red Hat Simple Signed, configure DOCKER_CONTENT_TRUST_BASE_SERVER with the <domain_name>.

  6. If the base image is on IBM Cloud Container Registry and Red Hat Simple Signed, you must configure the ICR_BASE_REPO and ICR_BASE_REPO_PUBLIC_KEY parameters. The following example shows the format for those two values:

     "ICR_BASE_REPO": "<region>.icr.io/<repo name>/<image name>:<tag>"
     "ICR_BASE_REPO_PUBLIC_KEY" : "<path to the public key>"
    
  7. To configure a Cloud Object Storage service to archive the application manifest files of your applications built by your HPSB container, add the following parameters to your sbs-config.json file.

    "COS_API_KEY_ID": "<your_cloud_apikey>",
    "COS_RESOURCE_CRN": "<your_cloud_resource_crn_id>",
    "COS_ENDPOINT": "<your_public_cos_endpoint>",
    "COS_AUTH_ENDPOINT": "https://iam.cloud.ibm.com/oidc/token",
    "MANIFEST_BUCKET_NAME": "<your_bucket_name>"
    

    The Manifest file will be stored in IBM Cloud Object Storage after the build is successful. COS_ENDPOINT specifies the public endpoint of your COS instance. Such as https://s3.us-east.cloud-object-storage.appdomain.cloud. Don't forget the leading https://. You need to create the bucket specified by MANIFEST_BUCKET_NAME if it doesn't exist.