The backstage QShift application has been designed to showcase QShift (Quarkus on OpenShift). It is composed of the following plugins and integrated with different backend systems:
Backstage plugin | Backend system |
---|---|
Core | GitHub |
Kubernetes | Red Hat OpenShift |
Quarkus | code.quarkus.io, Red Hat OpenShift Virtualization 4.14.3 |
Quarkus Console | Red Hat OpenShift |
ArgoCD front & backend | Red Hat OpenShift GitOps 1.11.1 |
Tekton | Red Hat OpenShift 1.13.1 |
Topology | Red Hat OpenShift |
Note: This backstage application is based on the backstage's version: 1.21.0
- Node.js (18 or 20)
- nvm, npm and yarn installed
- Read this blog post: https://medium.com/@chrisschneider/build-a-developer-portal-with-backstage-on-openshift-d2a97aca91ee
- GitHub client (optional)
- argocd client (optional)
Important: If you need to provision an OpenShift cluster with the required backend systems: ArgoCD, Tekton, etc, then go to the section Install me
This project allows to play with QShift using either Backstage:
The following section details the different commands to be used to deploy QShift on a new OCP cluster (e.g. 4.14.10)
To subscribe to the operator and create the needed CR
Note: The version of the operator could be different according to the ocp cluster version used but the platform will in this case bump the version for you. Take care as this project could take time !
cd manifest/installation/virt
kubectl create ns openshift-cnv
kubectl apply -f subscription-kubevirt-hyperconverged.yml
kubectl apply -f hyperConverged.yml
To install the customized fedora image packaging podman and socat, create now a DataVolume
CR and wait till the image will be imported
kubectl -n openshift-virtualization-os-images apply -f quay-to-pvc-datavolume.yml
To create a VM in the namespace where you plan to demo
oc project <MY_NAMESPACE>
kubectl create secret generic quarkus-dev-ssh-key --from-file=key=$HOME/.ssh/id_rsa.pub
kubectl apply -f quarkus-dev-virtualmachine.yml
Verify if the VMI is well running
kubectl get vm -n <MY_NAMESPACE>
NAMESPACE NAME AGE STATUS READY
cmoullia quarkus-dev 32s Running True
To subscribe to the operator and create the needed CR
cd manifest/installation/gitops
kubectl create ns openshift-gitops-operator
kubectl apply -f subscription-gitops.yml
To use ArgoCD with QShift, it is needed to delete the existing ArgoCD
CR and to deploy our ArgoCD
CR.
Note: Our CR includes different changes needed to work with QShift: sourceNamespaces
, extraConfig
and tls.termination: reencrypt
and resourceExclusions
Todo: The previous note should be documented to explain the changes needed !
kubectl delete argocd/openshift-gitops -n openshift-gitops
Substitute within the ArgoCD
CR the <MY_NAMESPACE> to be used using this command
cat argocd.tmpl | NAMESPACE=<MY_NAMESPACE> envsubst > argocd.yml
kubectl apply -f argocd.yml
Todo: Instead of deleting and recreating a new ArgoCD CR, we should patch it or install it using kustomize, helm chart. Example: https://github.com/redhat-cop/agnosticd/blob/development/ansible/roles_ocp_workloads/ocp4_workload_openshift_gitops/templates/openshift-gitops.yaml.j2
Patch the AppProject
CR to support to deploy the Applications
CR in different namespaces.
kubectl get AppProject/default -n openshift-gitops -o json | jq '.spec.sourceNamespaces += ["*"]' | kubectl apply -f -
Finally, create a new ClusterRoleBinding to give the Admin
role to the ServiceAccount openshift-gitops-argocd-application-controller
. That will allow it to manage the Applications
CR deployed in any namespace of the cluster.
cat << EOF | kubectl apply -f -
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: argocd-controller-admin
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: admin
subjects:
- kind: ServiceAccount
name: openshift-gitops-argocd-application-controller
namespace: openshift-gitops
EOF
To subscribe to the operator, execute this command
cd manifest/installation/tekton
kubectl apply -f subscription-pipelines.yml
Before to install and use our Backstage application, it is needed to perform some steps such as:
- Create an OpenShift project
- Provide your registry credentials (quay.io, docker, etc) as a
config.json
file
The commands described hereafter will help you to set up what it is needed:
-
Start first by cloning this project locally
git clone https://github.com/q-shift/backstage-playground.git cd backstage-playground
-
Log on to the ocp cluster
oc login --token=sha256 ...
which has been provisioned -
Create an OpenShift project:
oc new-project <MY_NAMESPACE>
Important: The commands documented hereafter assume that your use the project created:
oc project <MY_NAMESPACE>
-
Next create the following registry
config.json
file (or use yours). Provide the following registry: quay.io and docker as they are needed to build/push the image of the Quarkus container or to pull images from docker registry without the hassle of thedocker limit
.QUAY_CREDS=$(echo -n "<QUAY_USER>:<QUAY_TOKEN>" | base64) DOCKER_CREDS=$(echo -n "<DOCKER_USER>:<DOCKER_PWD>" | base64) QUAY_ORG=<QUAY_ORG> cat <<EOF > config.json { "auths": { "quay.io/${QUAY_ORG}": { "auth": "$QUAY_CREDS" }, "https://index.docker.io/v1/": { "auth": "$DOCKER_CREDS" } } } EOF
Important: The Git Org to define here should be the same as the one you will use when you scaffold a Quarkus application.
-
Deploy it using this command:
kubectl create secret generic dockerconfig-secret --from-file=config.json
-
Warning: To let ArgoCD to handle the
Applications
CR within your namespace, it is needed to patch the resourcekind: ArgoCD
to add your namespace using the field:.spec.sourceNamespaces
. When patched, the ArgoCD operator will roll out automatically the ArgoCD server.kubectl get argocd/openshift-gitops -n openshift-gitops -o json \ | jq '.spec.sourceNamespaces += ["<MY_NAMESPACE>"]' | kubectl apply -f -
-
And finally, create the service account
my-backstage
.kubectl create sa my-backstage
Note: This is needed to create the SA in order to get the secret generated and containing the token that we will use at the step
Deploy and use Backstage on OCP
We are now ready to deploy and use backstage within your project as documented at the following section.
A Backstage application uses an app-config.yaml configuration file to configure its front and backend application like the plugins accessing the backend systems.
As we cannot use a local config file as this is the case when you start backstage locally (yarn dev
), then we will use for ocp a configMap
and
define the sensitive information in a kubernetes secret
.
This kubernetes secret, which contains k=v pairs, will be mounted as a volume within the backstage's pod and will override the appo-config.yaml
file mounted also as a volume from a ConfigMap.
Trick: The backstage_env_secret.tmpl file contains what you need to get or set the sensitive information :-)
- Copy the template and save it:
backstage_env_secret.env
:cp manifest/templates/backstage_env_secret.tmpl backstage_env_secret.env
- Edit the file
backstage_env_secret.env
and set the different values using the commands or information between<command or trick>
- Create the kubernetes secret using the env file:
kubectl create secret generic my-backstage-secrets --from-env-file=backstage_env_secret.env
- To deploy backstage, create from the template
manifest/templates/argocd.tmpl
the argocd.yaml file and pass env variables to be substituted:cat manifest/templates/argocd.tmpl | NAMESPACE=<MY_NAMESPACE> DOMAIN=<OCP_CLUSTER_DOMAIN> envsubst > argocd.yaml kubectl apply -f argocd.yaml
Verify if backstage is alive using the URL: https://backstage-<MY_NAMESPACE>.<OCP_CLUSTER_DOMAIN>
and start to play with the template Create Quarkus Application
Create your app-config.qshift.yaml
file using the app-config.qshift.tmpl file included within this project.
Take care to provide the following password/tokens:
Type | How to get it |
---|---|
GitHub Personal Access Token | See backstage doc |
Argo CD Cluster password | kubectl -n openshift-gitops get secret/openshift-gitops-cluster -ojson | jq '.data."admin.password" | @base64d' |
Argo CD Auth token | curl -sk -X POST -H "Content-Type: application/json" -d '{"username": "'${ARGOCD_USER}'","password": "'${ARGOCD_PWD}'"}' "https://$ARGOCD_SERVER/api/v1/session" | jq -r .token |
Backstage's kubernetes Token | kubectl -n backstage get secret my-backstage-token-xxx -o go-template='{{.data.token | base64decode}}' |
Warning: If you use node 20, then export the following env var export NODE_OPTIONS=--no-node-snapshot
as documented here.
Next run the following commands:
yarn install
yarn start --config ../../app-config.qshift.yaml
yarn start-backend --config ../../app-config.qshift.yaml
You can now open the backstage URL http://localhodt:3000
, select from the left menu /create
and scaffold a new project using the template Create a Quarkus application
To delete the GitHub repository created like the ArgoCD resources on the QShift server when you scaffold a project using the Create a Quarkus Application
template, use the following commands
app=my-quarkus-app
gh repo delete github.com/<GIT_ORG>/$app --yes
ARGOCD_SERVER=openshift-gitops-server-openshift-gitops.apps.qshift.snowdrop.dev
ARGOCD_PWD=<ARGOCD_PWD>
ARGOCD_USER=admin
argocd login --insecure $ARGOCD_SERVER --username $ARGOCD_USER --password $ARGOCD_PWD --grpc-web
argocd app delete <MY_NAMESPACE>/$app-bootstrap --grpc-web -y
argocd app list --grpc-web -N <MY_NAMESPACE>