Creating a stack hub
What you’ll learn
In this guide you will learn how to configure and build a stack hub that defines the application stacks that you want to use to develop containerized applications in your organization.
A stack hub is the central control point for application stacks that you want to use in your organization. These stacks might be clones of public stacks or they might be customized to meet local requirements. For example, you might want to include templates with unique starter applications, specify a different test framework, or ensure that your applications are developed on specific software levels.
Before building a stack hub you should identify the stacks that you want to use for developing your microservice applications. Clone the available stacks and make any modifications that are needed. How to customize, package, and publish stacks is covered in the Customizing applications stacks guide.
This guide will cover how to build a stack hub that consolidates multiple application stacks for use in your organization, how to release your stack hub in GitHub, and how to use the assets in your deployment environment.
The following prerequisites apply to your local system:
- Git must be installed
- Docker must be installed
- To build assets for Codewind, Python 3 must be installed
Constructing a stack hub
Stack hubs are created from a configuration file. For a suitable starting point, clone the following repository, which contains example files:
git clone https://github.com/kabanero-io/kabanero-stack-hub.git
In this repository, you can find the following key files:
config/default_kabanero_config.yaml: the public stack hub configuration
example_config/example_repo_config.yaml: an example configuration that shows how to define multiple repositories and application stacks
scripts/hub_build.sh: a script to build stack hub index files
Understanding the configuration format
The format of the configuration file is shown in the following example:
# Template for repo-tools configuration name: <Repository name> description: <Repository description> version: <Repository version> stacks: - name: <Repository index name> repos: - url: <Reference to index file> exclude: - <stack name> include: - <stack name> image-org: <Organization containing images within registry> image-registry: <Image registry hosting images> nginx-image-name: <Image name for the generated nginx image, defaults to repo-index>
The options shown in the configuration file are described in the following list:
name:An identifier for this particular configuration.
description:A unique description for your configuration.
version:A version number, which might align with a release. For example, a Git release of your stack hub.
name:The name of a repository to build, which might contain one or more application stacks.
repos:An array of URLs that point to one or more stack index files that you want to include in this repository
exclude:(Optional) An array of stack names that you want to exclude from the repository. If no filtering is required, leave blank.
include:(Optional) An array of stack names that you want to include from the repository. If no filtering is required, leave blank.
image-org:(Optional) The name of the organization within the image registry where you want to store the docker images for included stacks. See Configuring public or private repositories.
image-registry:(Optional) The URL of the image registry where you want to store the stack docker images. See Configuring public or private repositories.
nginx-image-name:(Optional) The name assigned to the generated NGINX image. The default is
repo-index. See Configuring public or private repositories.
include: fields are mutually exclusive. Use only one or the other for a specific repository to avoid build errors.
Configuring public or private repositories
If your stacks and repositories are publicly available, leave the
image-registry fields blank.
If your stacks and repositories are hosted in a private environment that your deployment environment and tools cannot access, such as GitHub Enterprise, the build can create an NGINX image. This image can serve all the resources that are needed for each stack (including the index file) within your deployment environment without the need for authentication. Use the
image-registry fields to define the organization and URL where you store your registry images. You can optionally configure a name for your NGINX image, which you must push to the registry that your deployment environment can access. When deployed, the NGINX image serves the repository index files that you create as part of the build.
Configuring your stack hub
In this guide, you will change the example configuration file and use it build a stack hub definition. Follow these steps:
example_config/example_repo_config.yamlfile to include the following values for your stack hub:
# File: example_repo_config.yaml # My organization stack hub name: My.org Stack Hub description: Test configuration to build 2 index files for the default and incubator repos. version: 0.1.0 stacks: - name: default repos: - url: https://github.com/appsody/stacks/releases/latest/download/incubator-index.yaml exclude: - kitura - node-red - python-flask - starter - swift - java-microprofile - java-openliberty - nodejs - url: https://github.com/kabanero-io/collections/releases/download/0.9.0/kabanero-index.yaml include: - java-openliberty image-org: image-registry: nginx-image-name:
This example configuration file builds a single stack hub index file for your
defaulthub points to two index files,
exclude:options are used to filter from the available application stacks.
Save your changes.
You can create as many hub index files as you need from a single configuration file by following the format in the
example_config/example_repo_config.yaml file. For example, you might want to create an index file for your production environment with one set of application stacks and one for your development or test environments where you are building apps on different underlying software levels.
Building stack hub assets
Build your stack hub assets from the example configuration file by running the following command:
The output from the command shows how information is fetched from each index file, which the build process consolidates into a single file. Here is some sample output:
Config file: example_config/example_repo_config.yaml == Running pre_build.d scripts ==== Running prereq_check.sh == Done pre_build.d scripts Not retrieving or modifying any assets Creating consolidated index for default == fetching https://github.com/appsody/stacks/releases/latest/download/incubator-index.yaml == Adding stacks from index https://github.com/appsody/stacks/releases/latest/download/incubator-index.yaml ==== Adding stack nodejs-loopback 0.3.0 ==== Excluding stack swift 0.2.5 ==== Excluding stack node-red 0.1.1 ==== Excluding stack python-flask 0.2.3 ==== Excluding stack starter 0.1.2 ==== Excluding stack java-microprofile 0.2.26 ==== Adding stack java-spring-boot2 0.3.29 ==== Excluding stack kitura 0.2.6 ==== Excluding stack java-openliberty 0.2.11 ==== Excluding stack quarkus 0.3.3 ==== Excluding stack nodejs 0.3.5 ==== Adding stack nodejs-express 0.4.8 == fetching https://github.com/kabanero-io/collections/releases/download/0.9.0/kabanero-index.yaml == Adding stacks from index https://github.com/kabanero-io/collections/releases/download/0.9.0/kabanero-index.yaml ==== Excluding stack java-microprofile 0.2.27 ==== Adding stack java-openliberty 0.2.3 ==== Excluding stack java-spring-boot2 0.3.29 ==== Excluding stack nodejs-express 0.4.8 ==== Excluding stack nodejs 0.3.6 == Running post_build.d scripts ==== Running build_nginx.sh == Done post_build.d scripts
Switch to the
assets directory that is generated by the build to find the stack hub index file in two formats,
default-index.json. The JSON file format is required if you are developing applications by using Codewind.
default-index.yaml file to view the consolidated information for each stack in your configuration. For example, the last stack in the list is
- id: nodejs-express name: Node.js Express version: 0.4.8 description: Express web framework for Node.js license: Apache-2.0 language: nodejs maintainers: - name: Sam Roberts email: firstname.lastname@example.org github-id: sam-github default-template: simple src: https://github.com/appsody/stacks/releases/download/nodejs-express-v0.4.8/incubator.nodejs-express.v0.4.8.source.tar.gz templates: - id: kafka url: https://github.com/appsody/stacks/releases/download/nodejs-express-v0.4.8/incubator.nodejs-express.v0.4.8.templates.kafka.tar.gz - id: simple url: https://github.com/appsody/stacks/releases/download/nodejs-express-v0.4.8/incubator.nodejs-express.v0.4.8.templates.simple.tar.gz - id: scaffold url: https://github.com/appsody/stacks/releases/download/nodejs-express-v0.4.8/incubator.nodejs-express.v0.4.8.templates.scaffold.tar.gz requirements: docker-version: '>= 17.09.0' appsody-version: '>= 0.2.7' image: docker.io/appsody/nodejs-express:0.4.8
Congratulations! You have built your first stack hub index file that defines a set of filtered application stacks from multiple source repositories.
Releasing your stack hub
The next step is to host your index file somewhere that is accessible to developers and then create a release. To host the index file in a GitHub repository, follow these steps:
When you are happy with the content of your stack hub, push your repository to your GitHub organization.
In GitHub, click Releases, then click Draft a new release to create a release for your stack hub. Complete the information fields and upload your
default-index.yamlfile from your
/assetsfolder into the box indicated by Attach binaries by dropping them here or selecting them. For more information, see Creating releases.
Publish your release.
Finally, share the URL with your developers so that they can access the stack hub index file from their development environment. You can copy the URL from the Assets section of your release by right-clicking on the
default-index.yamlfile and choosing Copy Link Address. The URL containing the index file will be similar to
Configuring your Kubernetes environment
Your deployment environment also needs to know about the application stacks that should be used to build deployment containers. You must update your Kabanero operator custom resource definition (CRD) file to reference your stack hub index file.
Follow these steps:
Obtain a copy of your current Kabanero CR instance configuration.
To obtain a list of all Kabanero CR instances in the kabanero namespace, run the following command:
oc get kabaneros -n kabanero
To obtain the configuration for a specific CR instance, run the following command, substituting
<name>for the instance you are targeting:
oc get kabanero <name> -n kabanero -o yaml > kabanero.yaml
This example assumes that you kept the default
<name>, which is
kabanero.yamlfile that you generated in the last step.
Update the following section, which shows the configuration for stack repositories:
stacks: repositories: - name: https: url: skipCertVerification: [true|false] - name: https: url: skipCertVerification: [true|false]
repositorieslists the repositories to search for stacks
nameis the name of your repository
urlcontains the URL string for the
skipCertVerificationdetermines whether to verify the certificate before activating (default is
To change the desired state for a repository after the instance is deployed, you must edit each resource manually.
The following configuration can be used for the repository you created earlier:
stacks: repositories: - name: my-org-repository https: url: https://github.com/myorg/my-org-repository/releases/latest/download/my-org-repository-index.yaml
Save the file.
Apply the changes to your Kabanero CR instance with the following command:
oc apply -f kabanero.yaml -n kabanero
Applications that are developed using the stacks defined in your stack hub can now be deployed to your Kubernetes cluster.