diff --git a/build.sh b/build.sh index 9762c5bfe9..37d7422148 100755 --- a/build.sh +++ b/build.sh @@ -1,4 +1,4 @@ #!/usr/bin/env sh -cspell docs/**/*.md -mkdocs build \ No newline at end of file +cspell docs/**/**/*.md +mkdocs build diff --git a/cspell.json b/cspell.json index 52e7c713be..e4e833634f 100644 --- a/cspell.json +++ b/cspell.json @@ -74,7 +74,10 @@ "Hadolint", "aquasec", "datacenter", - "Grafana" + "Grafana", + "userdemo", + "projectdemo", + "ROKS" ], // flagWords - list of words to be always considered incorrect // This is useful for offensive words and common spelling errors. diff --git a/docs/adopting/use-cases/gitops/gitops-ace.md b/docs/adopting/use-cases/gitops/gitops-ace.md new file mode 100644 index 0000000000..1c30d000d0 --- /dev/null +++ b/docs/adopting/use-cases/gitops/gitops-ace.md @@ -0,0 +1,184 @@ +# Install App Connect on an existing cluster using GitOps + +_This is a work in progress, come back for updates._ + +Steps to install App Connect in an existing cluster using ArgoCD. + +## Pre-requisites +The following is required before proceeding to the next section. + +- Provision an OpenShift cluster. +- IBM Cloud Pak Entitlement Key + + +## Installation +1. Fork the [multi-tenancy-gitops](https://github.com/cloud-native-toolkit/multi-tenancy-gitops) repository and clone your fork. + ```bash + git clone git@github.com:{gitid}/multi-tenancy-gitops.git + ``` + +1. Install the Red Hat OpenShift GitOps operator. + ```bash + cd multi-tenancy-gitops + + oc apply -f 2-services/operators/openshift-gitops/ + ``` + +1. Update your repository to reference your forked repository. Search and replace `cloud-native-toolkit` GithUb Org references with your {gitid}. + +1. Create the bootstrap ArgoCD application. + ```bash + oc apply -f bootstrap.yaml -n openshift-gitops + ``` + +1. Generate an encrypted Secret containing the IBM Entitlement Key using Sealed Secret Operator. + - Install [kubeseal](https://github.com/bitnami-labs/sealed-secrets/blob/main/README.md) CLI. + - Encrypt IBM Entitlement Key Secret. + ```bash + NAMESPACE=tools + IBM_ENTITLEMENT_KEY= + + # Create Secret YAML containing Entitlement Key + oc create secret docker-registry ibm-entitlement-key \ + --docker-username=cp \ + --docker-server=cp.icr.io \ + --docker-password=${IBM_ENTITLEMENT_KEY} \ + --namespace=${NAMESPACE} \ + --dry-run=true -o yaml > delete-ibm-entitled-key-secret.yaml + + # Encrypt the secret using kubeseal and private key from the cluster + kubeseal -n ${NAMESPACE} --controller-name=sealedsecretcontroller-sealed-secrets --controller-namespace=sealed-secrets -o yaml < delete-ibm-entitled-key-secret.yaml > ibm-entitled-key-secret.yaml + ``` + +1. Apply the yaml manually or add to your gitops git repo to be deploy via ArgoCD. + ```bash + oc apply -f enc-ibm-entitled-key-secret.yaml + ``` + +1. Verify the infrastructure and cluster wide resources under the `3-infra` folder are created successfully. + ```bash + 3-infra/ + ├── argocd-apps + │   ├── consolelink.yaml + │   ├── consolenotification.yaml + │   ├── namespace-ci.yaml + │   ├── namespace-dev.yaml + │   ├── namespace-istio-system.yaml + │   ├── namespace-openldap.yaml + │   ├── namespace-qa.yaml + │   ├── namespace-sealed-secrets.yaml + │   ├── namespace-staging.yaml + │   └── namespace-tools.yaml + ├── consolelink + │   └── consolelink.yaml + ├── consolenotification + │   └── consolenotification.yaml + └── namespaces + ├── ci + │   ├── namespace.yaml + │   └── rolebinding.yaml + ├── dev + │   └── namespace.yaml + ├── istio-system + │   └── namespace.yaml + ├── openldap + │   └── namespace.yaml + ├── qa + │   └── namespace.yaml + ├── sealed-secrets + │   ├── namespace.yaml + │   └── operatorgroup.yaml + ├── staging + │   └── namespace.yaml + └── tools + ├── namespace.yaml + └── operatorgroup.yaml + ``` + ![ArgoCD deployments of 3-infra](images/argocd-cntk-3-infra.png){.center} + +1. Verify the operators and instances of custom resource definitions under the `2-services` folder are created successfully. + ```bash + 2-services/ + ├── active + │   ├── instances + │   │   └── argocd + │   └── operators + │   └── argocd + └── inactive + ├── instances + │   ├── argocd + │   │   ├── artifactory.yaml + │   │   ├── cert-manager-instance.yaml + │   │   ├── cntk-pipeline-tasks.yaml + │   │   ├── developer-dashboard.yaml + │   │   ├── ibm-mq-prod-instance.yaml + │   │   ├── ibm-mq-staging-instance.yaml + │   │   ├── ibm-platform-navigator-instance.yaml + │   │   ├── openldap.yaml + │   │   ├── pact-broker.yaml + │   │   ├── sealed-secrets-instance.yaml + │   │   ├── sonarqube.yaml + │   │   └── swaggereditor.yaml + │   ├── artifactory + │   │   ├── Chart.yaml + │   │   └── values.yaml + │   ├── cert-manager + │   │   └── instance.yaml + │   ├── cloud-native-toolkit + │   │   └── release-v2.6.10.yaml + │   ├── dev + │   ├── developer-dashboard + │   │   ├── Chart.yaml + │   │   └── values.yaml + │   ├── ibm-platform-navigator + │   │   └── ibm-platform-navigator.yaml + │   ├── openldap + │   │   ├── Chart.yaml + │   │   └── values.yaml + │   ├── pact-broker + │   │   ├── Chart.yaml + │   │   └── values.yaml + │   ├── prod + │   ├── sealed-secrets + │   │   └── instance.yaml + │   ├── sonarqube + │   │   ├── Chart.yaml + │   │   └── values.yaml + │   ├── staging + │   └── swaggereditor + │   ├── Chart.yaml + │   └── values.yaml + └── operators + ├── argocd + │   ├── cert-manager.yaml + │   ├── ibm-catalogs.yaml + │   ├── ibm-cp4i-operators.yaml + │   ├── ibm-foundations.yaml + │   ├── ibm-platform-navigator.yaml + │   ├── jaeger.yaml + │   ├── openshift-pipelines.yaml + │   └── sealed-secrets.yaml + ├── cert-manager + │   └── operator.yaml + ├── ibm-catalogs + │   ├── Chart.yaml + │   └── values.yaml + ├── ibm-cp4i-operators + │   ├── Chart.yaml + │   └── values.yaml + ├── ibm-foundation + │   ├── Chart.yaml + │   └── values.yaml + ├── ibm-platform-navigator + │   ├── Chart.yaml + │   └── values.yaml + ├── jaeger + │   ├── Chart.yaml + │   └── values.yaml + ├── openshift-pipelines + │   └── operator.yaml + └── sealed-secrets + ├── Chart.yaml + └── values.yaml + ``` + ![ArgoCD deployments of 2-services](images/argocd-ace-2-services.png) diff --git a/docs/adopting/use-cases/gitops/gitops-toolkit.md b/docs/adopting/use-cases/gitops/gitops-toolkit.md new file mode 100644 index 0000000000..64b007dbcb --- /dev/null +++ b/docs/adopting/use-cases/gitops/gitops-toolkit.md @@ -0,0 +1,106 @@ +# Install the Cloud Native Toolkit on an existing cluster using GitOps + +_This is a work in progress, come back for updates._ + +Steps to install the Cloud Native Toolkit in an existing OpenShift cluster using a declarative approach with ArgoCD. + + + +## Pre-requisites +The following is required before proceeding to the next section. + +- Provision an OpenShift cluster. +- Install the `oc` and `git` cli. +- Install the [Cloud Native Toolkit CLI](http://localhost:8000/learning/dev-setup.html#install-the-cloud-native-toolkit-command-line-interface-cli). + + +## Installation +1. Fork the [multi-tenancy-gitops](https://github.com/cloud-native-toolkit/multi-tenancy-gitops) repository and clone your fork. + ```bash + git clone git@github.com:{gitorg}/multi-tenancy-gitops.git + + cd multi-tenancy-gitops + ``` + +1. Update the cloned repository with your GitHub Organization. + - Search and replace all instances of `github.com/cloud-native-toolkit/multi-tenancy-gitops.git` with `github.com/{gitorg}/multi-tenancy-gitops.git`. + - Commit and push your changes to your fork. + ```bash + git commit -m "Update github organization" + git push origin master + ``` + +3. The gitops repository is structured into different layers (ie. `1-apps`, `2-services`, `3-infra`). Each layer is structured in a similar pattern consisting of the following: + - The `argocd` folder contains a set of ArgoCD Application YAMLs. + - The set of folder(s) in each layer contains the resource YAMLs which will be deployed. + ```bash + tree . -L 2 + . + ├── 0-bootstrap + │   └── argocd + ├── 1-apps + │   ├── argocd + │   └── instances + ├── 2-services + │   ├── argocd + │   ├── instances + │   └── operators + ├── 3-infra + │   ├── argocd + │   ├── clusterrole + │   ├── consolelink + │   ├── consolenotification + │   └── namespaces + ├── 4-rhacm + │   └── argocd + ├── README.md + └── bootstrap.yaml + ``` + - Each `argocd` folder contains an `active` and `inactive` sub-folder. For each layer, select the ArgoCD Appliation YAMLs to deploy and move them into the `active` folder. + ```bash + 1-apps/argocd/ + ├── active + └── inactive + + 2-services/argocd/ + ├── active + └── inactive + + 3-infra/argocd/ + ├── active + └── inactive + ``` + - Commit and push your changes to your fork. + ```bash + git commit -m "Update github organization" + git push origin master + ``` + +1. Install the Red Hat OpenShift GitOps operator using the commands below or directly from the OpenShift Web Console. An instance of ArgoCD will automatically be created in the `openshift-gitops` namespace. + ```bash + oc apply -f 2-services/operators/openshift-gitops/ -n openshift-operators + ``` + - Verify you can log on to the ArgoCD Web Console. + ``` + # ArgoCD Web Console URL + echo https://$(oc get route argocd-cluster-server -o jsonpath='{ .spec.host }' -n openshift-gitops) + + # Admin password + oc extract secret/argocd-cluster-cluster --to=- -n openshift-gitops + ``` + +1. Review and apply the custom ClusterRole permissions to the ArgoCD Application Controller service account. This is required for ArgoCD to create the required Kubernetes resources in target namespaces. + ```bash + oc apply -f 3-infra/clusterrole/ + ``` + +1. Create the bootstrap ArgoCD application. + The bootstrap application will create the parent ArgoCD Application for each layer (YAMLs are located in `0-bootstrap` folder). + The parent ArgoCD Applications will subsequently create the ArgoCD Applications in the `/argocd/active` directory. + + Depending on what resources have been selected, it will take some time for the ArgoCD to deploy the resources. + ```bash + oc apply -f bootstrap.yaml -n openshift-gitops + ``` + +1. From the OpenShift Web Console, verify the resources (ie, operators, namespaces, etc) have been successfully created and/or deployed. diff --git a/docs/adopting/use-cases/gitops/images/argocd-ace-2-services.png b/docs/adopting/use-cases/gitops/images/argocd-ace-2-services.png new file mode 100644 index 0000000000..b29967b0e8 Binary files /dev/null and b/docs/adopting/use-cases/gitops/images/argocd-ace-2-services.png differ diff --git a/docs/adopting/use-cases/gitops/images/argocd-cntk-3-infra.png b/docs/adopting/use-cases/gitops/images/argocd-cntk-3-infra.png new file mode 100644 index 0000000000..7d164304d7 Binary files /dev/null and b/docs/adopting/use-cases/gitops/images/argocd-cntk-3-infra.png differ diff --git a/docs/learning/dev-setup.md b/docs/learning/dev-setup.md index a1e21aed84..6b94975e15 100644 --- a/docs/learning/dev-setup.md +++ b/docs/learning/dev-setup.md @@ -15,7 +15,7 @@ This guide assumes that you have some basic knowledge of Kubernetes, Docker, and ## Cluster Command Line Tools -You will be using the command line for some of the tasks you will learn about as you work through the learning material. +You will be using the command line for some of the tasks you will learn about as you work through the learning material. If you are using the Open Labs environment, then you can skip installing command line tools locally as the Open Labs environment provides a web-based command line. @@ -66,9 +66,9 @@ The Personal Access Token only needs to be generated once because it is associat - Navigate to [Developer Settings](https://github.com/settings/tokens){: target=_blank} and generate a new token; name it something like "CI pipeline" - Select `public_repo` scope to enable git clone - Select `write:repo_hook` scope so the pipeline can create a web hook - + ![Pipeline OAuth scopes](./images/pipeline-scopes.png) - + - The GitHub UI will never again let you see this token, so be sure to save the token in your password manager or somewhere safe that you can access later on ### IBM Cloud account @@ -93,7 +93,7 @@ The Cloud-Native Toolkit CLI needs to be installed in all development environmen To install the Cloud-Native Toolkit CLI run the following command: ```shell -curl -sL shell.cloudnativetoolkit.dev | shell - +curl -sL shell.cloudnativetoolkit.dev | sh - source ~/.bashrc || source ~/.zshrc ``` diff --git a/docs/overview/whats-new.md b/docs/overview/whats-new.md index 6b81700e28..2aac31d7ce 100644 --- a/docs/overview/whats-new.md +++ b/docs/overview/whats-new.md @@ -2,10 +2,16 @@ - +## May 25, 2021 + +- The Workshop got updated with a new [Artificial Intelligence](https://cloudnativetoolkit.dev/workshop/ai) +- New experimental support to deploy via GitOps the [Cloud Native Toolkit](https://cloudnativetoolkit.dev/adopting/use-cases/gitops/gitops-toolkit.html) and [IBM Cloud Pak App Connect](https://cloudnativetoolkit.dev/adopting/use-cases/gitops/gitops-ace.html) + + ## Jan 28, 2021 [Cloud Native Toolkit Workshop](https://cloudnativetoolkit.dev/workshop) released. The workshop in a box environment is easy and quick to setup with hands on labs including videos. diff --git a/docs/resources/workshop/ai.md b/docs/resources/workshop/ai.md new file mode 100644 index 0000000000..6034a68770 --- /dev/null +++ b/docs/resources/workshop/ai.md @@ -0,0 +1,123 @@ +# Deploy an Artificial Intelligence Microservice + + + +1. Prerequisites + - The instructor should [Setup Workshop Environment](setup.md) + - The student should [Setup CLI and Terminal Shell](setup.md#4-optional-auto-configure-terminal-shell) + +1. Instructor will provide the following info: + - OpenShift Console URL (OCP_CONSOLE_URL) + - The username and password for OpenShift and Git Server (default values are user1, user2, etc.. for users and `password` for password). + +1. Set `TOOLKIT_USERNAME` environment variable. + If you are participation in a workshop replace `userdemo` with your assigned username (ex. `user01`). + ```bash + TOOLKIT_USERNAME=userdemo + ``` + +1. **(Skip if using KubeAdmin or IBM Cloud)** Login to OpenShift using `oc` + - If using IBM Cloud cluster then login with your IBM account email and IAM API Key or Token by using the **Copy Login Command** + ![Login](../images/login.jpg) + - If using a cluster that was configured with the workshop scripts outside IBM Cloud then use respective assigned username (ex. `user01`), and the password is `password` + ```bash + oc login $OCP_URL -u $TOOLKIT_USERNAME -p password + ``` + +1. Set `TOOLKIT_PROJECT` environment variable + If you are participation in a workshop replace `projectdemo` based on your assigned username (ex. `project01`). + ```bash + TOOLKIT_PROJECT=projectdemo + ``` + +1. Create a project/namespace using your project as prefix, and `-dev` and suffix + ```bash + oc sync $TOOLKIT_PROJECT-dev + ``` + +1. Fork application template git repo + - Open Developer Dashboard from the OpenShift Console + ![Developer Dashboard](images/developer-dashboard.jpg){.center} + - Select Starter Kits + ![Starter Kits](images/starter-kits-ai.jpg){.center} + - Select One in our case **Artificial Intelligence Microservice** + - Click Fork + - Login into GIT Sever using the provided username and password (ie `userdemo` and `password`) + - Click **Fork Repository** + +1. Setup environment variable `GIT_URL` for the git url using the value from previous step or as following. + **Note:** We are including username/password in git url for simplicity of this lab. You would **NOT** want to do this in your development environment. + ```bash + GIT_REPO=ai-model-object-detector + GIT_URL=http://${TOOLKIT_USERNAME}:password@$(oc get route -n tools gogs --template='{{.spec.host}}')/${TOOLKIT_USERNAME}/${GIT_REPO} + echo GIT_URL=${GIT_URL} + + ``` + +1. Clone the git repository and change directory + ```bash + cd $HOME + git clone $GIT_URL app + cd app + + ``` + +1. Create a Tekton pipeline for the application + ```bash + oc pipeline --tekton + ``` + - Use down/up arrow and select `ibm-general` + - Enter **n** and hit Enter to disable image scanning + - Hit Enter to enable Dockerfile linting + - Hit Enter to select default health endpoint `/` + - Open the url to see the pipeline running in the OpenShift Console + +1. Verify that Pipeline Run completed successfully + - On the OpenShift web console select **Pipelines** + - At the top of the page select your development project/namespace created above (ex. `project01-dev`) + - The app pipeline last run status should be **Succeeded** + ![Pipeline Run](images/pipeline-run.jpg){.center} + +1. Review the Pipeline Tasks/Stages. + - Click on the last run + ![Last pipeline run](images/last-run.jpg){.center} + - Click on the **Test** task and view the logs + ![Test task](images/test-task.jpg){.center} + - Open SonarQube from Console Link + - Open Registry from Console Link + - Open Artifactory from Console Link + +1. The **gitops** step of the pipeline triggers Argo CD to deploy the app to QA. Select **Developer** perspective, select project `$TOOLKIT_PROJECT-qa` and then select **Topology** from the Console and verify the application running + ![Last pipeline run](images/deploy-qa.jpg){.center} + +1. Open the application route url and try out the application using the swagger UI or append `/app` to the URL to load Web UI for the Application. You can download the this sample [picture](https://raw.githubusercontent.com/IBM/MAX-Object-Detector/master/samples/baby-bear.jpg) to test the app + ![open url](images/open-url.jpg){.center} + ![ai app](images/ai-app-baby-bear.jpg){.center} + + +1. Make a change to the application in the git repository and see the pipeline running again from the Console. Lets change the Machine Learning being used from `ssd_mobilenet_v1` to `faster_rcnn_resnet101` + ```bash + git config --local user.email "${TOOLKIT_USERNAME}@example.com" + git config --local user.name "${TOOLKIT_USERNAME}" + sed -i 's/ssd_mobilenet_v1/faster_rcnn_resnet101/' Dockerfile + git add . + git commit -m "update model" + git push -u origin master + + ``` + +1. Verify that change in Git Server and Git WebHook + - Open Git Dev from Console Link + - Navigate to user app git repository + - Review the recent commit + - Review the webhook recent delivery + ![webhook](images/webhook.jpg){.center} + +1. Verify that a new Pipeline starts successfully + +1. Verify that the App manifests are being updated in the `gitops` repo in the git account `toolkit` under the `qa` directory. + - Open Git Ops from Console Link + - Select toolkit/gitops git repository + ![gitops](images/gitops.jpg){.center} + +1. Congratulations you finished this lab, continue with lab [Promote an Application using CD with GitOps and ArgoCD](./cd) diff --git a/docs/resources/workshop/cd.md b/docs/resources/workshop/cd.md index 3d88086bfe..e968c57d6a 100644 --- a/docs/resources/workshop/cd.md +++ b/docs/resources/workshop/cd.md @@ -9,52 +9,60 @@ Click on image below to launch video: 1. Prerequisites - Complete lab [Deploy an Application using CI Pipelines with Tekton](ci.md). -1. Set `TOOLKIT_USERNAME` environment variable replace `user1` with assigned usernames - - ```shell - TOOLKIT_USERNAME=user1 - +1. Set `TOOLKIT_USERNAME` environment variable. + If you are participation in a workshop replace `userdemo` with your assigned username (ex. `user01`). + ```bash + TOOLKIT_USERNAME=userdemo ``` -1. Set `TOOLKIT_PROJECT` environment variable replace `project1` or `projectx` based on user id assigned +1. **(Skip if using KubeAdmin or IBM Cloud)** Login to OpenShift using `oc` + - If using IBM Cloud cluster then login with your IBM account email and IAM API Key or Token by using the **Copy Login Command** + ![Login](../images/login.jpg) + - If using a cluster that was configured with the workshop scripts outside IBM Cloud then use respective assigned username (ex. `user01`), and the password is `password` + ```bash + oc login $OCP_URL -u $TOOLKIT_USERNAME -p password + ``` - ```shell - TOOLKIT_PROJECT=project1 +1. Set `TOOLKIT_PROJECT` environment variable + If you are participation in a workshop replace `projectdemo` based on your assigned username (ex. `project01`). + ```bash + TOOLKIT_PROJECT=projectdemo ``` 1. Verify Application is deployed in **QA** - Select ArgoCD from the Console Link and login using OpenShift login - - Filter Applications by name `${TOOLKIT_PROJECT}-qa` (ie project1-qa) - - Select the application `master-qa-${TOOLKIT_PROJECT}-app` (ie master-qa-project1-app) + - Filter Applications by name `${TOOLKIT_PROJECT}-qa` (ie project01-qa) + - Select the application `master-qa-${TOOLKIT_PROJECT}-app` (ie master-qa-project01-app) + ![Argo CD App](images/argo-app.jpg) 1. Verify Application is running in the QA namespace corresponding to your username `${TOOLKIT_PROJECT}-qa` - Select **Developer** perspective, select project `${TOOLKIT_PROJECT}-qa` and then select **Topology** from the Console and see the application running + ![Deploy QA](images/deploy-qa.jpg) 1. Setup environment variable `GIT_OPS_URL` for the git url using the value from previous step or as following - - ```shell + ```bash GIT_OPS_URL=http://${TOOLKIT_USERNAME}:password@$(oc get route -n tools gogs --template='{{.spec.host}}')/toolkit/gitops echo GIT_OPS_URL=${GIT_OPS_URL} + ``` 1. Clone the git repository and change directory - - ```shell + ```bash cd $HOME git clone $GIT_OPS_URL cd gitops + ``` 1. Review the `qa` and `staging` directory in the git repository - - ```shell + ```bash ls -l qa/ ls -l staging/ + ``` 1. Promote the application from **QA** to **STAGING** by copying the app manifest files using git - - ```shell + ```bash git config --local user.email "${TOOLKIT_USERNAME}@example.com" git config --local user.name "${TOOLKIT_USERNAME}" @@ -63,21 +71,24 @@ Click on image below to launch video: git add . git commit -m "Promote Application from QA to STAGING environment for $TOOLKIT_PROJECT" git push -u origin master + ``` 1. Verify Application is deployed in **STAGING** - Select ArgoCD from the Console Link and login using OpenShift login - - Filter Applications by namespace `${TOOLKIT_PROJECT}-staging` (ie project1-staging) - - Select the application `master-staging-${TOOLKIT_PROJECT}-app` (ie master-staging-project1-app) + - Filter Applications by namespace `${TOOLKIT_PROJECT}-staging` (ie project01-staging) + - It might take a couple minutes for the application to show up + - Select the application `master-staging-${TOOLKIT_PROJECT}-app` (ie master-staging-project01-app) - Click **Refresh** + ![Argo CD App staging](../images/argo-app-staging.jpg) -1. Verify Application is running in the **STAGING** namespace corresponding to your username `${TOOLKIT_PROJECT}-qa` +1. Verify Application is running in the **STAGING** namespace corresponding to your username `${TOOLKIT_PROJECT}` - Select **Developer** perspective, select project `${TOOLKIT_PROJECT}-staging` and then select **Topology** from the Console and see the application running + ![Deploy Staging](../images/deploy-staging.jpg) 1. Propose a change for the Application in **STAGING** - Update the replica count and create a new git branch in remote repo - - ```shell + ```bash cat > staging/${TOOLKIT_PROJECT}/app/values.yaml <> README.md @@ -101,11 +110,13 @@ Click on image below to launch video: - Navigate to user app git repository - Review the recent commit - Review the webhook recent delivery + ![webhook](images/webhook.jpg){.center} 1. Verify that a new Pipeline starts successfully 1. Verify that the App manifests are being updated in the `gitops` repo in the git account `toolkit` under the `qa` directory. - Open Git Ops from Console Link - Select toolkit/gitops git repository + ![gitops](images/gitops.jpg){.center} 1. Congratulations you finished this lab, continue with lab [Promote an Application using CD with GitOps and ArgoCD](cd.md) diff --git a/docs/resources/workshop/images/ai-app-baby-bear.jpg b/docs/resources/workshop/images/ai-app-baby-bear.jpg new file mode 100644 index 0000000000..e772fe4e0a Binary files /dev/null and b/docs/resources/workshop/images/ai-app-baby-bear.jpg differ diff --git a/docs/resources/workshop/images/argo-app-staging.jpg b/docs/resources/workshop/images/argo-app-staging.jpg new file mode 100644 index 0000000000..79a54fbc2e Binary files /dev/null and b/docs/resources/workshop/images/argo-app-staging.jpg differ diff --git a/docs/resources/workshop/images/argo-app-staging2.jpg b/docs/resources/workshop/images/argo-app-staging2.jpg new file mode 100644 index 0000000000..c815c85c8e Binary files /dev/null and b/docs/resources/workshop/images/argo-app-staging2.jpg differ diff --git a/docs/resources/workshop/images/argo-app.jpg b/docs/resources/workshop/images/argo-app.jpg new file mode 100644 index 0000000000..3c238d085d Binary files /dev/null and b/docs/resources/workshop/images/argo-app.jpg differ diff --git a/docs/resources/workshop/images/deploy-qa copy.jpg b/docs/resources/workshop/images/deploy-qa copy.jpg new file mode 100644 index 0000000000..9f1205355f Binary files /dev/null and b/docs/resources/workshop/images/deploy-qa copy.jpg differ diff --git a/docs/resources/workshop/images/deploy-qa.jpg b/docs/resources/workshop/images/deploy-qa.jpg new file mode 100644 index 0000000000..9f1205355f Binary files /dev/null and b/docs/resources/workshop/images/deploy-qa.jpg differ diff --git a/docs/resources/workshop/images/deploy-staging.jpg b/docs/resources/workshop/images/deploy-staging.jpg new file mode 100644 index 0000000000..5c2466cf78 Binary files /dev/null and b/docs/resources/workshop/images/deploy-staging.jpg differ diff --git a/docs/resources/workshop/images/deploy-staging2.jpg b/docs/resources/workshop/images/deploy-staging2.jpg new file mode 100644 index 0000000000..25f87453b3 Binary files /dev/null and b/docs/resources/workshop/images/deploy-staging2.jpg differ diff --git a/docs/resources/workshop/images/developer-dashboard.jpg b/docs/resources/workshop/images/developer-dashboard.jpg new file mode 100644 index 0000000000..824a7cd1c9 Binary files /dev/null and b/docs/resources/workshop/images/developer-dashboard.jpg differ diff --git a/docs/resources/workshop/images/gitops copy.jpg b/docs/resources/workshop/images/gitops copy.jpg new file mode 100644 index 0000000000..5b8d4f3973 Binary files /dev/null and b/docs/resources/workshop/images/gitops copy.jpg differ diff --git a/docs/resources/workshop/images/gitops-pr1.jpg b/docs/resources/workshop/images/gitops-pr1.jpg new file mode 100644 index 0000000000..9eec252d63 Binary files /dev/null and b/docs/resources/workshop/images/gitops-pr1.jpg differ diff --git a/docs/resources/workshop/images/gitops.jpg b/docs/resources/workshop/images/gitops.jpg new file mode 100644 index 0000000000..5b8d4f3973 Binary files /dev/null and b/docs/resources/workshop/images/gitops.jpg differ diff --git a/docs/resources/workshop/images/last-run.jpg b/docs/resources/workshop/images/last-run.jpg new file mode 100644 index 0000000000..17650ea562 Binary files /dev/null and b/docs/resources/workshop/images/last-run.jpg differ diff --git a/docs/resources/workshop/images/open-url.jpg b/docs/resources/workshop/images/open-url.jpg new file mode 100644 index 0000000000..45d03ec84e Binary files /dev/null and b/docs/resources/workshop/images/open-url.jpg differ diff --git a/docs/resources/workshop/images/pipeline-run.jpg b/docs/resources/workshop/images/pipeline-run.jpg new file mode 100644 index 0000000000..91e0ebc9ea Binary files /dev/null and b/docs/resources/workshop/images/pipeline-run.jpg differ diff --git a/docs/resources/workshop/images/starter-kits-ai.jpg b/docs/resources/workshop/images/starter-kits-ai.jpg new file mode 100644 index 0000000000..3e6898bad1 Binary files /dev/null and b/docs/resources/workshop/images/starter-kits-ai.jpg differ diff --git a/docs/resources/workshop/images/starter-kits.jpg b/docs/resources/workshop/images/starter-kits.jpg new file mode 100644 index 0000000000..135ff66d8a Binary files /dev/null and b/docs/resources/workshop/images/starter-kits.jpg differ diff --git a/docs/resources/workshop/images/test-task.jpg b/docs/resources/workshop/images/test-task.jpg new file mode 100644 index 0000000000..ef1ac98c2f Binary files /dev/null and b/docs/resources/workshop/images/test-task.jpg differ diff --git a/docs/resources/workshop/images/webhook.jpg b/docs/resources/workshop/images/webhook.jpg new file mode 100644 index 0000000000..eaf98fc2cb Binary files /dev/null and b/docs/resources/workshop/images/webhook.jpg differ diff --git a/docs/resources/workshop/inventory.md b/docs/resources/workshop/inventory.md index 70dbfccd65..ceebf68731 100644 --- a/docs/resources/workshop/inventory.md +++ b/docs/resources/workshop/inventory.md @@ -14,25 +14,24 @@ Click on image below to launch video: - OpenShift Console URL (OCP_CONSOLE_URL) - The username and password for OpenShift and Git Server (default values are user1, user2, etc.. for users and `password` for password). -1. Set `TOOLKIT_USERNAME` environment variable replace `user1` with assigned usernames - - ```shell - TOOLKIT_USERNAME=user1 - +1. Set `TOOLKIT_USERNAME` environment variable. + If you are participation in a workshop replace `userdemo` with your assigned username (ex. `user01`). + ```bash + TOOLKIT_USERNAME=userdemo ``` -1. **(Skip if using KubeAdmin or IBM Cloud)** Login into OpenShift using `oc` - - If using IBM Cloud cluster then login with your IBM account email and IAM API Key or Token, if using a cluster that was configured with the workshop scripts outside IBM Cloud then use `user1` or respective assigned username, and the password is `password` - - ```shell +1. **(Skip if using KubeAdmin or IBM Cloud)** Login to OpenShift using `oc` + - If using IBM Cloud cluster then login with your IBM account email and IAM API Key or Token by using the **Copy Login Command** + ![Login](../images/login.jpg) + - If using a cluster that was configured with the workshop scripts outside IBM Cloud then use respective assigned username (ex. `user01`), and the password is `password` + ```bash oc login $OCP_URL -u $TOOLKIT_USERNAME -p password ``` -1. Set `TOOLKIT_PROJECT` environment variable replace `project1` or `projectx` based on user id assigned - - ```shell - TOOLKIT_PROJECT=project1 - +1. Set `TOOLKIT_PROJECT` environment variable + If you are participation in a workshop replace `projectdemo` based on your assigned username (ex. `project01`). + ```bash + TOOLKIT_PROJECT=projectdemo ``` 1. Create a project/namespace using your project prefix, and `-dev` and suffix diff --git a/docs/resources/workshop/setup.md b/docs/resources/workshop/setup.md index f3800fe882..6f046da30e 100644 --- a/docs/resources/workshop/setup.md +++ b/docs/resources/workshop/setup.md @@ -25,7 +25,7 @@ Create an OpenShift Cluster for example: curl -sfL get.cloudnativetoolkit.dev | sh - ``` -## 3. Setup Workshop +## 3. Setup IBM Cloud Native Toolkit Workshop - Install the foundation for the workshops @@ -34,20 +34,62 @@ Create an OpenShift Cluster for example: ``` !!!Note - The username and password for Git Admin is `toolkit` `toolkit` + - The username and password for Git Admin is `toolkit` `toolkit` + - Usernames `user01` through `user15` are configured with a password of `password`. + - Username `userdemo` is configured with the password `password`. You can use this username if using the workshop environment + for self study or giving a demo. If you are preparing the environment for a workshop you can remove `userdemo` + b y running the `uninstall-userdemo.sh` script which is part of the [workshop](https://github.com/cloud-native-toolkit/cloud-native-toolkit-workshop) scripts. -!!!Todo - Should this be moved out of setup and into the student section of the workshop? +## 4. (Optional) Customization of the IBM Cloud Native Toolkit Workshop -## 4. (Optional) Auto configure Terminal Shell +- You can customize the Workshop environment by cloning the [workshop](https://github.com/cloud-native-toolkit/cloud-native-toolkit-workshop) repo -- You can use [IBM Cloud Shell](https://cloud.ibm.com/shell), the [OpenLabs Shell](https://developer.ibm.com/openlabs/openshift) or your local workstation. More details in [Toolkit Dev Setup](../../learning/dev-setup.md) and [Toolkit CLI](../../reference/cli.md). - Run the following command on Cloud, Linux or MacOS shell: +- Some of the most common customizations are: + + - You can create more than 15 users by setting a `USER_COUNT` environment variable. For example to configure 30 users use the command + ```bash + export USER_COUNT=30 + ``` + + - You can create more than 15 projects by setting a `PROJECT_COUNT` environment variable. For example to configure 30 projects use the command + ```bash + export PROJECT_COUNT=30 + ``` + +- Once you have finished configuring your customizations, login to the cluster from the cli and run the `scripts/install.sh` script to perform the install. + +- You can also add additional users to the workshop clusters. + - Create a file with one user id per line. + **IMPORTANT: there needs to be newline after the last entry.** + For example a `users.txt` file with content. + ```bash + additionaluserID + anotheruserID + someuserID + + ``` + + !!! note "" + For Openshift clusters on IBM Cloud (ROKS) the user ids are their IBM IDs (email address) all lowercase with an uppercase `IAM#` prefix added to the beginning. + ```bash + IAM#additionaluserid@email.com + IAM#anotheruserid@email.com + IAM#someuserid@email.com + + ``` + + - Create a `ADDITIONAL_USERS_FILE` environment variable with the path and name of the file. + ```bash + export ADDITIONAL_USERS_FILE=users.txt + ``` + - The additional users will be granted the `self-provisioner` role, meaning they can create new Openshift Projects. + If you wish to remove this permission set an environment + variable `ADDITIONAL_USERS_SELF_PROVISIONER` with a value of `N` + ```bash + export ADDITIONAL_USERS_SELF_PROVISIONER=N + ``` + + - Once you have finished configuring the additional users, login to the cluster from the cli and run the `scripts/13-ocp-additional-users.sh` script. - ```shell - curl -sL shell.cloudnativetoolkit.dev | bash - - source ~/.bashrc || source ~/.zshrc - ``` - Be sure to follow the instructions provided to enable the changes in the current terminal session. diff --git a/docs/resources/workshop/terminal.md b/docs/resources/workshop/terminal.md new file mode 100644 index 0000000000..a9b8676906 --- /dev/null +++ b/docs/resources/workshop/terminal.md @@ -0,0 +1,13 @@ + +# Setup Terminal Shell + +- You can use [IBM Cloud Shell](https://cloud.ibm.com/shell), the [OpenLabs Shell](https://developer.ibm.com/openlabs/openshift) or your local workstation. More details in [Toolkit Dev Setup](../../learning/dev-setup.md) and [Toolkit CLI](../../reference/cli.md). + Run the following command on Cloud, Linux or MacOS shell: + + ```shell + curl -sL shell.cloudnativetoolkit.dev | bash - + source ~/.bashrc || source ~/.zshrc + + ``` + + Be sure to follow the instructions provided to enable the changes in the current terminal session. \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index 37fad56d38..c17933de5a 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -34,7 +34,15 @@ plugins: 'learn': 'learning/fast-start.md' 'learning': 'learning/fast-start.md' 'workshop': 'resources/workshop/workshop.md' - 'resource/workshop': 'resources/workshop/workshop.md' + 'resources/workshop': 'resources/workshop/workshop.md' + 'workshop/setup': 'resources/workshop/setup.md' + 'workshop/terminal': 'resources/workshop/terminal.md' + 'workshop/ci': 'resources/workshop/ci.md' + 'workshop/inventory': 'resources/workshop/cd.md' + 'workshop/appmod': 'resources/workshop/appmod.md' + 'workshop/ai': 'resources/workshop/ai.md' + 'learning/gitops-int/gitops-with-cloud-native-toolkit': 'adopting/use-cases/gitops/gitops-toolkit.md' + 'learning/gitops-int/gitops-with-app-connect': 'adopting/use-cases/gitops/gitops-ace.md' markdown_extensions: - attr_list - admonition @@ -63,11 +71,13 @@ nav: - Learning the Toolkit: - Try it: - Overview: resources/workshop/workshop.md - - Setup: resources/workshop/setup.md + - Setup Cluster: resources/workshop/setup.md + - Setup Terminal: resources/workshop/terminal.md - Continuous integration: resources/workshop/ci.md - Continuous delivery: resources/workshop/cd.md - 3-tier application: resources/workshop/inventory.md - Application modernization: resources/workshop/appmod.md + - Artificial Intelligence: resources/workshop/ai.md - Basics: - Learning Overview: learning/fast-start.md - Developer setup: learning/dev-setup.md @@ -115,6 +125,9 @@ nav: - Add a new use case: adopting/use-cases/add-use-case.md - Build an Operator: adopting/use-cases/operator/operator.md - App Connect REST API workflow: adopting/use-cases/ace-pipeline/ace-pipeline.md + - GitOps: + - Toolkit Install: adopting/use-cases/gitops/gitops-toolkit.md + - App Connect Install: adopting/use-cases/gitops/gitops-ace.md - Reference: - Reference: reference/reference.md - Command Line Tool: reference/cli.md