Installation Process Kubernetes
This will guide you through the installation process for Kubernetes.
The Cloud Solutions Workbench can be installed via helm chart on Kubernetes.
After the installation finished successfully, you will have
- a running instance of Solution Builder
- a running instance of Solution Hub
Please note that both components are not fully configured after the installation.
Roles in the installation process
Kubernetes cluster administrator
The cluster administrator is responsible for:
- Creating namespaces
- Creating kubernetes secrets
- Deploying cluster-wide resources (CRDs, Roles) via helm chart
Namespace administrator
The namespace administrator is responsible for:
- Deploying Cloud Solutions Workbench helm chart
- Installing Envoys on prepared namespaces
- Providing necessary configuration data
Namespaces
You will need to have different namespaces for different purposes as described below
| Namespace | Description |
|---|---|
| k5-tools | The namespace that has the tool setup installed and basic configuration. |
| k5-projects | Kubernetes namespace used as deployment targets. In Solution Builder, they are referred to as deployment targets as they are only used to deploy and execute microservices. In Solution hub, they are referred to as k5-projects and in other cases it can be referred to as Envoy. You can have at least one or more deployment targets as per your preference. |
Before you begin
Please make sure that all system requirements are met, especially the Kubernetes setup including Tekton installation.
In order to install Cloud Solutions Workbench the following requirements should be met on the machine:
Step 1: Prerequisites
- Create namespace
${CSW_NAMESPACE}
kubectl create namespace csw
- Download
csw-admin-setup.tgz - Download
csw-chart.tgz - Create image pull secret:
kubectl apply -n ${CSW_NAMESPACE} -f - <<EOF
apiVersion: v1
kind: Secret
metadata:
name: knowis-csw-pull-secret
data:
.dockercfg: eyJyZ...==
type: kubernetes.io/dockercfg
EOF
- Create or copy (cluster) wildcard certificate
kubectl apply -n ${CSW_NAMESPACE} -f - <<EOF
kind: Secret
apiVersion: v1
metadata:
name: k5-public-route-wildcard-tls
data:
tls.crt: LS0tL...=
tls.key: LS0tL...=
type: kubernetes.io/tls
EOF
Step 2: Deploy Admin resources via helm chart
The helm command below will deploy all necessary Custom Resource Definitions (CRDs) and Roles within the cluster.
helm install -n ${CSW_NAMESPACE} -f values.yaml csw-admin-setup.tgz ./
Step 3: Deploy CSW helm chart
The helm command provided below will facilitate the deployment of Cloud Solutions Workbench within the cluster.
helm upgrade --install csw -n ${CSW_NAMESPACE} -f values.yaml csw-chart.tgz ./ \
--set global.domain="my.cluster.com" \
--set global.network.egressPolicy.enabled=false \
--set global.network.ingressPolicy.enabled=false \
--set global.network.routing.routes.enabled=false \
--set global.network.routing.ingress.enabled=true \
--set global.network.services.certification.selfsigned.enabled=true \
--set global.tekton.imageStreams.initialize=false
Extended configuration
For more detailed configuration, the following values can be used for more specific configuration. All values are optional and can be edited at any time.
| Variable | Description | Default |
|---|---|---|
global.documentation.enabled | A boolean value that enables or disables the deployment of the documentation in the cluster | false |
global.endpoints.assetManager.host | A String value that defines the url for the k5-asset-manager Route | 'k5-asset-manager-YOUR_INGRESS_DOMAIN' |
global.endpoints.configurationManagement.host | A String value that defines the url for the k5-configuration-management Route | 'k5-configuration-YOUR_INGRESS_DOMAIN' |
global.endpoints.designer.host | A String value that defines the url for the k5-designer Route | 'k5-designer-YOUR_INGRESS_DOMAIN' |
global.endpoints.hub.host | A String value that defines the url for the k5-hub Route | 'k5-hub-YOUR_INGRESS_DOMAIN' |
global.endpoints.query.host | A String value that defines the url for the k5-query Route | 'k5-query-YOUR_INGRESS_DOMAIN' |
global.frontend.changePasswordLink | A String value that defines the url to change the password in your OIDC provider | '/account/#/security/signingin' |
global.frontend.defaultTimeout | A Integer value that defines the default timeout in the frontend in milliseconds. | 30000 |
global.network.egressPolicy.allowList | A list with domains that Cloud Solutions Workbench is allowed to connect to. Each entry in the list is a key-value pair that has either the key dnsName with a domain name as value (without protocol) or cidrSelector with an IP address range in CIDR format as value. See also Network Policies | - |
global.network.egressPolicy.enabled | A boolean value that enables or disables the EgressNetworkPolicy | true |
global.network.ingressPolicy.enabled | A boolean value that enables or disables the NetworkPolicy | true |
global.routes.annotations | Key-value pairs that are added as annotations to every route (Care: Adding annotations removes the default ones, see right column) | haproxy.router.openshift.io/hsts_header: max-age=31536000;includeSubDomains;preload haproxy.router.openshift.io/rate-limit-connections: 'true' haproxy.router.openshift.io/rate-limit-connections.concurrent-tcp: '25' |
service-builder.k5-asset-manager.routingExpose.enabled | A boolean value that enables or disables the route for k5-asset-manager | false |
service-builder.k5-cli-provider.routes.annotations | A String value that defines additional route annotations name for the k5-cli-provider. They are not overwriting the annotations, which are defined byglobal.routes.annotations nor the default annoations of global.routes.annotations. | - |
service-builder.k5-code-generation-provider.routes.annotations | A String value that defines additional route annotations name for the k5-code-generation-provider. They are not overwriting the annotations, which are defined byglobal.routes.annotations nor the default annoations of global.routes.annotations. | - |
service-builder.k5-designer-backend.mongoDb.dbName | A String value that defines the used database name for the k5-designer-backend | 'k5-solution-designer' |
service-builder.k5-git-integration-controller.mongoDb.dbName | A String value that defines the used database name for the k5-git-integration-controller | 'k5-git-integration' |
service-builder.k5-pipeline-manager.tekton.workspace.storage | A String value that defines size of the requested storage for the pipeline run workspace PVC | '1024Mi' |
service-builder.k5-pipeline-manager.tekton.workspace.storageClassName | A String value that defines the storage class name that is used for the workspace PVC for a new PipelineRun (if not set the default StorageClass of the cluster is used) | - |
service-builder.k5-pipeline-manager.tekton.cleanup.enabled | A boolean value that enables or disables the cleanup of the created PipelineRuns and related PVC | false |
service-builder.k5-pipeline-manager.tekton.cleanup.scheduleInMinutes | A String value that defines in minutes how often the cleanup job should be scheduled | '30' |
service-builder.k5-pipeline-manager.tekton.cleanup.keepLastPipelineRuns | A String value that defines the number of the last PipelineRuns the cleanup job should keep per service project (can be disabled with the value '-1'), e.g. the value '2' would mean every time the cleanup job runs, all PipelineRuns will be deleted except the latest 2 of every service project | '1' |
service-builder.k5-pipeline-manager.tekton.cleanup.keepLastPipelineRunsCompletedBefore | A String value that defines which PipelineRuns the cleanup job should keep by the completed timestamp in minutes (can be disabled with the value '-1'), e.g. the value '60' would mean every time the cleanup job runs, all PipelineRuns will be deleted that have been completed at least 60 minutes ago | '-1' |
service-builder.k5-git-integration-controller.encryption.encryptionAlgorithm | Encryption Algorithm that should be used to encrypt and decrypt user git token stored in mongoDB. Supported values are "aes-256-gcm", "aes-192-gcm", "aes-128-gcm", “aes-256-cbc", “aes-192-cbc" and “aes-128-cbc". Changing the encryptionAlgorithm will cause data loss, because user tokens are encrypted with that and can't be decrypted without it! In this case all encrypted data is invalid, hence all users have to remove and renew the saved Git Tokens and API Keys. | 'aes-256-gcm' |
Next steps
With your successful installation of Cloud Solutions Workbench, you can go on to configure the product which is a mandatory step.
Troubleshooting
k5 clone is not working on MacOs (base64 issue)
If the k5 clone command is failing on MacOS like this
k5 clone -s MYSOLUTION -p "my-git"
========= Cloning Solution to filesystem =================================================
--------- > Authenticating ---------------------------------------------------------------
--------- > Cloning Solution from Solution Git Repository --------------------------------
Cloning into '/dev/MYSOLUTION'...
fatal: unable to access 'https://my-git/MYSOLUTION.git/': error setting certificate verify locations:
CAfile: /Users/MyUser/.k5/k5-cli/default/designtime.ca.crt
CApath: /Users/MyUser/.k5/k5-cli/default
[ERROR] Cloning failed, removing directory: /dev/MYSOLUTION
Then please verify, if the file /Users/MyUser/.k5/k5-cli/default/designtime.ca.crt has proper base64 encoded
values only. To do so, open the file and verify, that all lines between the -----BEGIN CERTIFICATE-----
and -----END CERTIFICATE----- do not exceed 64 characters. For manual and local fixing you can adjust the lines by
breaking after 64 characters. And verify, that this is solving the experienced issue.
To fix it generally, the value of global.truststore.trustMap.identity must be adjusted in a similar way. Afterwards
the setup of k5 must be reset by downloading the designtime.config.json and
executing k5 setup --file ./cli-config.json.
How to analyze JWT in case of unauthorized responses
If a request is rejected and the response contains invalid_token, then it is helpful to decode the JWT itself by using
for example jwt.io. So it is easier to see, if the JWT is decode-able and what kind of content it
has, and to understand, what might cause the unexpected rejections.
Understanding the reason of The iss claim is not valid
If a request is rejected and the response contains invalid_token in combination of The iss claim is not valid, then
the JWT was created by an OIDC provider using a different issuer URL, than the configured one.
It is helpful to decode the JWT itself by using for example jwt.io and check the value of iss. That must be the same as it is configured described by configuring OIDC provider for solutions and configuring deployment targets.