Setting up Kabanero Enterprise collections in your GitHub Enterprise organization with the Cloud Pak for Applications command-line interface (CLI)

You can use the cloud pak installer to add Kabanero Enterprise collections to your GitHub Enterprise organization and then build your Kabanero Enterprise collections repository. An advantage of working with collections in your GitHub Enterprise instance is that you can customize the collections for your needs and share them with your team members.

It is not required that you set up collections in a GitHub Enterprise organization, but it is recommended. Before you can set up collections, Kabanero Enterprise must be installed and your GitHub Enterprise instance must be reachable by the OpenShift Container Platform (OCP) cluster.

The following steps describe how to set up collections and share them with your team:

  1. Add Kabanero Enterprise collections to your GitHub Enterprise organization.
  2. Build the Kabanero Enterprise collections.
  3. Share the collections with your team.
  4. If needed, configure Appsody to get the Kabanero Enterprise collection images from the internal Docker registry of your cluster.

Step 1: Add Kabanero Enterprise collections to your GitHub Enterprise organization

Use the Cloud Pak for Applications installer setup-collections command to create the kabanero-collections repository in your GitHub Enterprise organization and add Kabanero Enterprise collections to the repository.

  1. Create a GitHub Enterprise organization for use by you and your team. You can use an existing organization but it is recommended to have a separate organization for the Kabanero Enterprise collections.

  2. Ensure that you have one or more teams in your GitHub Enterprise organization.

  3. Create a GitHub Enterprise personal access token, if you don't have one already. The token must be able to create and access repositories.

  4. Open a command line at the same location as where you ran the installer install command.

  5. Open an editor on the config.yaml file, which is in the data directory, and add your GitHub values to the configuration file.

    github:
         url: "<GitHub_URL>"
         organization: "<GitHub_organization>"
         teams: ["<GitHub_team1>", "<GitHub_team2>"]
         token: "<GitHub_token>"
    

    where:

    • <GitHub_URL> is the URL for your GitHub Enterprise. An example URL is https://github.mycompany.com.
    • <GitHub_organization> is the GitHub Enterprise organization that you created in step 1. An example organization value is cp4apps.
    • <GitHub_team1> is the GitHub Enterprise team that you created in step 2. An example team name is cp4apps-admins. For more than one team, separate team names with a comma.
    • <GitHub_token> is your GitHub Enterprise personal access token. Alternatively, the token can be passed by using the GITHUB_TOKEN environment variable. An example token value is b88a676f99g36088e10abc7ea86ae7hh94ee6.
  6. Run the Cloud Pak for Applications installer setup-collections command. The command creates the kabanero-collections repository under the specified GitHub Enterprise organization and populates it with the Kabanero Enterprise collections. If the kabanero-collections repository already exists, the command tries to update the existing collections and opens a pull request with the changes.

    docker run -u 0 -t \
               -v $PWD/data:/installer/data:z \
               -e LICENSE=accept \
               "$ENTITLED_REGISTRY/cp/icpa/icpa-installer:4.0.1" setup-collections
    

    If you are passing your GitHub Enterprise access token as an environment variable, make sure to add -e GITHUB_TOKEN to the setup-collections command.

    To see details on the command results, view the setup-collections.log.<timestamp> file in the logs directory.

  7. If the setup-collections command opened a pull request, review the pull request changes, resolve any conflicts, and merge the pull request. Optionally, create a new GitHub release of the collections repository.

Step 2: Build Kabanero Enterprise collections

Use the Cloud Pak for Applications installer build-collections command to build your Kabanero Enterprise collections repository.

  1. Log in to your OCP cluster.

    oc login https://<your_cluster_hostname> -u <username> -p <password>
    
  1. Run the Cloud Pak for Applications installer build-collections command.

    docker run -v ~/.kube:/root/.kube:z -u 0 -t \
               -v $PWD/data:/installer/data:z \
               -e LICENSE=accept \
               -e ENTITLED_REGISTRY -e ENTITLED_REGISTRY_USER -e ENTITLED_REGISTRY_KEY \
               "$ENTITLED_REGISTRY/cp/icpa/icpa-installer:4.0.1" build-collections
    

    The build-collections command triggers a Tekton pipeline to build the collections. You can track the pipeline execution in the Tekton dashboard. The command can take up to an hour to complete, based on the number of collections and size of the dependencies.

    After the build-collections command completes successfully, a new Kabanero Enterprise instance is deployed in your cluster. The new Kabanero Enterprise instance is configured with the collections from your GitHub Enterprise organization.

    By default, the command uses the master branch of the kabanero-collections repository. To use a different branch or tag, pass the following argument to the build-collections command. For <revision>, specify the different branch or tag name.

    -e "{'kabanero': {'github':{'collections':{'branch':'<revision>'}}}}"
    

    The build-collections command can be run multiple times. Thus, in the future, you can build the collections again, as needed.

Step 3: Share the collections with your team

Share the Collection Hub information on the Kabanero Enterprise instance page with your team. The team then can configure their Codewind tools External link icon or use the Appsody CLI External link icon with your collections and build cloud native applications using these collections.

Step 4: Configure Appsody to get the Kabanero Enterprise collection images

Additional Appsody configuration might be required to get the Kabanero Enterprise collection images from the internal Docker registry of your cluster.

  1. If you use an insecure route for the Docker registry, configure Docker to access the internal Docker registry External link icon of your cluster.

  2. Get the route for the internal Docker registry of your cluster. You might have to expose the route External link icon to the internal registry first.

    oc get route -n openshift-image-registry default-route -o=jsonpath='{.status.ingress[0].host}'
    
  3. Log in to the internal Docker registry.

    docker login "<registry>" -u "unused" -p "$(oc whoami -t)"
    

    <registry> is the endpoint of the internal Docker registry of your cluster. An example endpoint is default-route-openshift-image-registry.apps.mycluster.ibm.com.

    You can pass any value for the -u field; the token contains all necessary information. If the user name contains a colon, then the login fails. For more information, see the OCP 4.2 documentation.

  4. Edit the .appsody/.appsody.yaml file in your home directory and update the images: field to specify the endpoint of the internal Docker registry.

    ...
    images: "<registry>"
    ...
    

What to do next

From the Cloud Pak Console, click Set up dev tools and configure development tools.