Creating a Jenkins X cluster


Creating a Jenkins X cluster

Cluster installation and configuration in CloudBees Jenkins X Distribution is possible through Jenkins X Boot, a command that allows users to create Kubernetes clusters without running through various commands for configuring storage, pipeline, GitOps, and other resources.

Jenkins X cluster prerequisites

In order to create a cluster in CloudBees Jenkins X Distribution, you must have the following configured:

  • A Google Cloud Platform (GCP) account for creating kubernetes clusters

  • The Kubernetes command-line tool, which can be installed to your local installation using the jx install command:

    jx install dependencies -d kubectl
  • Access to the GitHub remote Git provider, which allows users to create organizations and multiple user accounts:

    • An Organization from which you invite existing users (in this example, the organization is called acmecorp). Create an organization by clicking the + button at the top right of the GitHub project page or through the Create an organization page.

    • A GitHub user account for creating and managing development repositories (for example acmeuser). Invite the user to your organization.

    • A bot user that automates pull request notifications and creates preview environments for quick validation and acceptance for code merging. The bot account must have a token created by your organization that authenticates the bot and allows it to perform various tasks on the repositories within your organization. In the examples, a GitHub account named acmebot is used.

Create a Kubernetes cluster

The cluster creation process on CloudBees Jenkins X Distribution(run via the command jx boot) requires performing a pre-configuration procedure to successfully complete the cluster installation process:

  1. Run jx create cluster at the command-line to initialize the cluster on your Google Kubernetes Engine (GKE) account with a specified name, for example acmecluster1:

    jx create cluster gke --skip-installation -n acmecluster1
    1. The program opens a web browser to choose the email address associated with your GCP account, then prompts you to allow the Google Cloud SDK to access your account.

    2. Back at the command-line, the jx create cluster program prompts you to choose your project from the available list.

    3. The program prompts you to choose the Zone nearest to where you would like to install your cluster. For example, if you want your cluster to serve users primarily in the east coast of the United states, you choose us-east1-b from the available list.

    4. The program runs automatically through default questions and begins creating the cluster in your specified zone.

  2. Run jx profile to set the correct installation profile for CloudBees Jenkins X Distribution support:

    jx profile cloudbees

Add Jenkins X to your cluster

You should now be in your local copy of the Jenkins X Boot configuration environment by running the jx boot program.

Run Jenkins X Boot at the command-line:

jx boot

For CloudBees Jenkins X Distribution version 1 users, you must run the jx boot command with an added compatibility option:

jx boot --versions-ref=9e45b38ba380d823cbdecfc3c175592da64e08f0

The interactive command-line tool guides you through the process of configuring and installing the resources needed to complete your GitOps development environment:

  1. The program prompts you to choose your Google Cloud Project from the available list

  2. The program prompts you for the Cluster Name, which you previously chosen (in this example, acmecluster1).

  3. The program prompts you for a Git Owner or your GitHub account (in this example, acmecorp).

  4. The program prompts you to enter a Storage Bucket URLs for saving various storage resources:

    1. Logs: You can use an existing storage bucket URL or press Enter and a bucket will be created for you.

    2. Reports: You can use an existing storage bucket URL or press Enter and a bucket will be created for you.

    3. Repository: You can use an existing storage bucket URL or press Enter and a bucket will be created for you.

  5. If you are prompted to upgrade your Jenkins X binaries or Platform at this stage of installation, press N to refuse the upgrade.

  6. The program prompts you to enter a Jenkins X administrator Username. You can use your current GitHub account for consistency (in this example, acmecorp).

    1. The program prompts you to enter a password for the Jenkins X administrator

  7. The program asks you for a Pipeline Bot Git username (for example acmebot). This creates a bot for automating your GitOps process by promoting code from your development environment to your staging and/or production environments.

    1. Create a new GitHub account strictly for the build control bot

    2. Invite the bot account to your organization

    3. Create a Git token for the Pipeline Bot with the correct permissions via this GitHub Link and copy the 40 character token

      Important
      The 40 character token generated by GitHub is only shown once so you must copy this immediately before you close the browser tab or window, as the token cannot be retrieved once it is displayed.
    4. Paste the copied GitHub token created for the Pipeline Bot when prompted

  8. The program asks if you would like to configure an external Docker Registry. Press Enter for No, and your docker images will be privately stored on the Google Container Registry by default.

If you have any questions or feedback on the CloudBees Jenkins X Distribution documentation, send them to jx-feedback@cloudbees.com.