Skip to Content

Setting up BMC Helix Deployment Engine

​

Set up the containerized BMC Helix Deployment Engine in your Kubernetes cluster to deploy BMC Helix Innovation Suite and Service Management applications. 

The containerized BMC Helix Deployment Engine consists of the following tools. These tools are used by the Jenkins pipelines to deploy BMC Helix Service Management applications.

  • Gitea: Git server with preconfigured repositories that are used to store the deployment artifacts.
  • Jenkins Master: CI/CD engine with preconfigured pipelines.
  • Jenkins Agent: Build worker with Ansible, Helm, kubectl, and Python.

 

Related topics

System requirements

BMC Helix Deployment Engine overview

FAQ

Success

Skills required

  • Using Jenkins
  • Using Linux

See Recommended skill set and trainings

Before you begin

Make sure that you meet the following requirements: 

  • Kubernetes cluster: A cluster with one of the supported platforms. For the supported platform, see System requirements.
  • Namespace: A separate dedicated namespace for BMC Helix Deployment Engine.
    Do not use the BMC Helix Service Management namespace to set up BMC Helix Deployment Engine.
    Make sure that the deployment user has access to the BMC Helix Deployment Engine namespace.
  • Storage class: A storage class with ReadWriteOnce permission.
    You can use file storage     or block storage type.
  • Virtual machine: A Linux virtual machine or jump box with one of the following supported operating systems:
    • RHEL or CentOS 8.x, 9.x
    • Rocky Linux 8.x, 9.x
    • Oracle Linux 8.x, 9.x
    • Alma Linux 8.x, 9.x
    • Ubuntu 22.04, 24.04 LTS
    • Debian 12.x
  • Sizing: Minimum cluster resources required for running services. 
    See Sizing and scalability considerations .
  • Connectivity: Virtual machine with network connectivity to the Kubernetes cluster.
    Internet access is not required.
  • Kubeconfig: A valid ~/.kube/config file with access to the Kubernetes cluster.
    If kubectl or Helm are not installed on the virtual machine, the BMC Helix Deployment Engine uses the binaries provided in the included k8s-tools/ directory.
  • Deployment script: Downloaded and extracted the helix-sm-deployment-engine-2026101.1.00.00.zip file.
    See Downloading the installation files.
  • Container images: BMC Helix Deployment Engine container images synchronized with your local registry. 

    The BMC Helix Deployment Engine container images are configured in the de-images.yaml file. The repository structure is as follows:

    <IMAGE_REGISTRY>/<REGISTRY_ORG>/<bmchelix>:<tag>

    ​​​​​​Make sure that the following images are available in your local container registry:

    ImageDescription
    de-jenkins-masterJenkins master server.
    de-jenkins-agentJenkins build agent with Ansible, Helm, and kubectl.
    de-bootstrapBootstrap job for Jenkins configuration.
    de-repo-seederSeeds Git repositories in Gitea.
    de-jenkins-refreshRefresh job for Jenkins pipelines.
    giteaGitea Git server.
    de-repo-seeder-sr Smart Reporting Git repositories in Gitea.

    For information about accessing the images, see Setting up a Harbor repository to synchronize container images. 

  • Service accounts: The service accounts are created by default when you set up BMC Helix Deployment Engine. If you do not have permissions to create service accounts, a cluster administrator must create the service accounts before you set up BMC Helix Deployment Engine. The BMC Helix Deployment Engine uses the following service accounts:​​​​​
    Service accountDescription
    deployment-engineService account for all workload pods such as Gitea, Jenkins Master, Jenkins Agent, and jobs.
    deployment-engine-bootstrap

    Service account for bootstrap job.

    This account requires Kubernetes API access to create secrets.

  • Deployment user permissions: A deployment user with only the following required namespace-scoped permissions. The ​​​​cluster administrator access is not required.
    ResourcePermissions
    deploymentscreate, update, get, list, delete
    servicescreate, update, get, list, delete
    secretscreate, update, get, list, delete
    configmapscreate, update, get, list, delete
    persistentvolumeclaimscreate, update, get, list, delete
    ingressescreate, update, get, list, delete
    jobscreate, update, get, list, delete
    podsget, list
    pods/logget
    serviceaccountscreate, update, get, list, delete
    rolescreate, update, get, list, delete
    rolebindingscreate, update, get, list, delete

    If the deployment user does not have the required permissions, a cluster administrator can provide the required permissions by using the rbac-deployment-user.yaml file.

To provide permissions to the deployment user

Perform this task if the deployment user does not have cluster administrator permissions. 

  1. Log in to the Kubernetes cluster as an administrator.
  2. Edit the rbac-deployment-user.yaml file.
  3. Replace the <namespace> parameter with the BMC Helix Deployment Engine namespace value and the <your-username> parameter with the deployment username value.
  4. Apply the changes with the administrator privileges by using the following command:
    For Kubernetes:
    kubectl apply -f rbac-deployment-user.yaml

    For OpenShift:
    oc apply -f rbac-deployment-user.yaml

To create service accounts

  1. Log in to the cluster as an administrator.
    You must have permissions to create roles and role bindings.
  2. To apply the RBAC resources, run the following command:kubectl apply -f rbac-bootstrap.yaml -n <BMC Deployment Engine namespace>

     

  3. In the deployment-engine-config.env file, set the CREATE_SERVICE_ACCOUNTS parameter value as false.

                                                                                                                                                                                                                                                                                                                                                                                      ​​​

To set up BMC Helix Deployment Engine

  1. Log in to the BMC Helix Deployment Engine virtual machine.
  2. In the deployment-engine-config.env file, update the following parameters:
  3. ParameterDescriptionExample value
    NAMESPACE Specify the BMC Helix Deployment Engine namespace.helixde
    STORAGE_CLASS_NAMESpecify the storage class namestandard
    IMAGE_REGISTRYSpecify the local registry name.

    your-registry.example.com

    REGISTRY_ORGSpecify the value as bmchelix.bmchelix
    IMAGE_REGISTRY_USER

    Specify the user name to log in to your local container registry.

    		admin
    IMAGE_REGISTRY_PASSWORDSpecify the password to log in to your local container registry.secret
    IMAGE_PULL_SECRETSpecify the name used to create the Kubernetes image registry secret. registry-secret
    JENKINS_USER

    The default Jenkins administrator user is admin.

    Do not modify the default value.

    		admin
    JENKINS_PASSSpecify the Jenkins password.your-secure-password
    GITEA_ADMIN_USERThe default gitea administrator is ciadmin. Do not modify the default value.ciadmin
    GITEA_ADMIN_PASSSpecify the Gitea password.your-secure-password
    KUBECONFIG_FILESpecify the full path to the .kube/config file./home/your-user/.kube/config
    OPENSHIFT_ENABLEDSpecify the value as true for OpenShift clusters, for other clusters specify the value as false.false
    INGRESS_CLASS

    Specify the Ingress class name of the NGINX Ingress Controller that you used while installing BMC Helix Platform.

    The default value is nginx.

    		nginx
    JENKINS_INGRESS_ENABLEDSpecify the value as true if you are using Ingress controller, else specify the value as false.true
    JENKINS_HOSTNAMESpecify the Jenkins host name.jenkins.example.com
    GITEA_INGRESS_ENABLEDSpecify the value as true if you are using Ingress controller, else specify the value as false.false
    GITEA_HOSTNAMESpecify the Gitea host name.gitea.example.com
    SMART_REPORTINGSet the value as true to deploy the repositories and jobs required to install Smart Reporting.false

     

  4. To run the deployment script, run the following command:

    ./deployment-engine.sh

    This command performs the following actions:

    • Renders Helm values from configuration
    • Creates registry and kubeconfig secrets
    • Deploys Gitea, Jenkins Master, and Jenkins Agent
    • Seeds Git repositories
    • Triggers Jenkins jobs to fetch Jenkins files
    Information

    If any error occurs during the script execution, you can rerun the script. The script uses an idempotent helm upgrade and re-execution does not impact the existing setup.

    After the script execution is complete, Jenkins is fully configured with all required credentials, including kubeconfig and pipeline dry runs. 
    If you encounter issues, refer to the troubleshooting information.

                                                                                                                                                                                                                                                                                                                                                                                         

To access the the Jenkins UI

You can access the Jenkins UI by using any one of the following methods:

MethodDescription
Using Ingress
​​​​

Use this method for production environments.

Jenkins URL: https://<JENKINS_HOSTNAME>

Gitea URL: https://<GITEA_HOSTNAME>

Using external IP

If Ingress is not enabled in your environment, expose the service by using NodePort, ClusterIP with an External IP, LoadBalancer, or any other appropriate method.

Example to expose the service by using ClusterIP with External IP:

  1. To patch the services to expose through external IP, run the following command:
    For Jenkins, kubectl patch service jenkins-master -n <NAMESPACE> -p '{"spec":{"externalIPs":["<IP_ADDRESS>"]}}'
    For Gitea, kubectl patch service gitea -n <NAMESPACE> -p '{"spec":{"externalIPs":["<IP_ADDRESS>"]}}'
    Use a routable IP address to the cluster worker nodes. You can use the same IP for both the services as the services use different ports.
  2. To access Jenkins, use the URL http://<IP_ADDRESS>:8080.
    To access Gitea, use the URL http://<IP_ADDRESS>:3000.
Using port forward

Use this method for testing and development environments.

  1. For Jenkins, run the following command: 
    kubectl port-forward svc/jenkins-master 8080:8080 -n <NAMESPACE>
    For Gitea, run the following command: kubectl port-forward svc/gitea 3000:3000 -n <NAMESPACE>

  2. To access Jenkins, use the URL http://localhost:8080.
    To access Gitea, use the URL http://localhost:3000.

Important: If you are accessing Jenkins or Gitea from a remote machine through the jump box IP, add --address 0.0.0.0 to the port-forward command.

To refresh the kubeconfig credentials

The kubeconfig credentials are configured when you setup BMC Helix Deployment Engine. To refresh the credentials, perform the following steps:

  1. Log in to Jenkins server by using the following URL:
    http://<Jenkins server host name>:<Jenkins port>
  2. To update the Kubernetes secret, perform the following steps:
    1. In the kubeconfig file, update the secret.
    2. To run the refresh script, run the following command:
      ./refresh-kubeconfig.sh

Troubleshooting

Refer to the troubleshooting information if you encounter any of the following issues while setting up BMC Helix Deployment Engine.

Issue Resolution

The bootstrap job fails.

To view the logs, run the following command:

kubectl logs -n <namespace> -l job-name=jenkins-master-bootstrap
The agent has connectivity issue.

To view the agent secret and logs, run the following commands:

kubectl get secret jenkins-agent-jnlp -n <namespace>
kubectl logs -n <namespace> deploy/jenkins-agent

The kubeconfig file has issues.

To view the Kubernetes secret and logs, run the following commands:

kubectl get secret jenkins-kubeconfig -n <namespace>
kubectl exec -n <namespace> deploy/jenkins-agent -- ls -la /home/jenkins/.kube/


Where to go from here

Next task

Back to process

If you are finished installing BMC Helix Platform services, return to the appropriate installation or upgrade process:

 

​

 

Tip: For faster searching, add an asterisk to the end of your partial query. Example: cert*

BMC Helix Service Management Deployment 26.1.01