Riser Workshop v1 #
Thank you for your interest in learning and improving Riser. This Workshop is intended to be instructor led. The goal is to capture your experience with core App Deployment and debugging with Riser.
ℹ️ While this workshop is designed to be self-contained, the full Riser documentation is available to you via the links on the left. If you do wish to review the documentation, be sure to open a topic in a separate tab as to not lose your position in the Workshop.
Prerequisites #
Prior to the workshop you should have received a set of instructions to ensure that you’re development environment is setup to participate. Please ensure the following:
- Ensure that you have a recent version of the following
- Enable the minikube ingress addon:
minikube addons enable ingress - Create a minikube cluster using Kubernetes 1.17.7. For the best results use the following settings:
minikube start --cpus=4 --memory=8192 --kubernetes-version=1.17.7. You may need to adjust CPU and memory settings depending on your hardware. - Create a GitHub repo for Riser’s state (e.g.
https://github.com/your-name/riser-state).- Riser requires write access to this repo. It is recommended that you create a Deploy Key and give it write permissions. You may also use a Personal Access Token.
ℹ️ While the Riser demo will work on any Kubernetes cluster, it is recommended for the Workshop that you use Minikube to ensure a consistent experience between participants.
Step 1 - Installing the demo #
The Riser demo allows you to experiment with Riser on your own Kubernetes cluster. Please use the following steps to install the demo.
- Ensure that minikube is started and that
kubectl config current-contextis pointing to the minikube cluster. - In a new terminal window, run
minikube tunnel. Ensure it establishes the tunnel and let it run in the background. - Download the latest Riser CLI for your platform and put it in your path.
- Run
riser demo installand follow the instructions. You may skip the last step, “Try out the testdummy app”, as this is covered later in Workshop. - Optional: If you don’t have a local DNS server, you may wish to set an env var
GATEWAY_IPto your gateway IP: e.g.export GATEWAY_IP=10.1.2.3. This will be used later forcurlcommands.
Step 2 - Creating your first Riser App #
The app that we’re creating today will be called testdummy. Riser does not manage the building of your app nor its Docker images. For simplicity, we will be utilizing prebuilt images of a preexisting testdummy app.
- Create a directory for your app (e.g.
~/apps/testdummy)cdinto the directory.- You should run all future
risercommands from this directory.
- Create and initialize your app:
riser apps init testdummy- Edit the TODOs in
app.yamlwhere necessary - The Docker image is
tshak/testdummy. Do not specify the docker tag. testdummyalready listens on port 8000
- Edit the TODOs in
- Verify that your app exists in
riser apps list
ℹ️ Riser reads theapp.yamlin the current directory and uses information like the App’s name and namespace so that you don’t have to specify them every time you run therisercommand.
Step 3 - Your first deployment #
- Check the status via
riser status - Deploy the docker tag
0.1.1to thedemoenvironment:riser deploy 0.1.1 demo - Check the status of your deployment
- Once your deployment is Ready, you can curl your URL at
https://testdummy.apps.demo.riser- If you do not have a local DNS server, use
curl -k https://testdummy.apps.demo.riser --resolve "testdummy.apps.demo.riser:443:${GATEWAY_IP}", whereGATEWAY_IPis the IP of the gateway IP assigned by the Riser demo installer. A production Riser installation would use a DNS server as well as valid SSL certificates, so the curl is usually more straightforward e.g.curl https://testdummy.apps.prod.yourdomain.net.- Use
riser demo statusto display your gateway IP again if required.
- Use
- If you do not have a local DNS server, use
- Visit your state repo on GitHub and review the commits made by Riser
- The
/riser-configfolder contains the Riser config used to generate the state - The
/state/demo/riser-managedfolder contains all Riser managed state for thedemoenvironment
- The
Step 4 - Your next deployment #
- Verify the
versionendpoint of the testdummy athttps://testdummy.apps.demo.riser/versionreturns0.1.1 - Deploy the docker tag
0.1.2to thedemoenvironment - Check the status of your deployment
- Once the new deployment is Ready, verify the
versionendpoint
Step 5 - Configure your app #
Riser loosely prescribes the 12-factor App methodology. As such, all deploy-time configuration should be made as environment variables. Open ./app.yaml and add the following environment variables:
name: testdummy
# ...omitted...
env:
MEANING: 42
# This allows us to view all env vars at the /env endpoint
TESTDUMMY_ENABLE_ENV: "true"
- Add the env vars as shown above
- Deploy the docker tag
0.1.2of thedemoenvironment - Check the status of your deployment and note the revision number.
- Visit https://testdummy.apps.demo.riser/env to see all env vars
ℹ️ Each Riser deployment is considered unique and therefore gets a unique Revision number. This is true even if you deploy with the same docker tag or the same App config
Step 6 - Configure Secrets #
Since we do not want to store secrets in plain text, Riser provides a mechanism to encrypt your secrets for your App. Secrets encrypted at rest and bound to your App at runtime via environment variables.
- Save a new secret to the
demoenvironment:riser secrets save mysecret SuPeRSeCrEt demo - Your secret should be present in
riser secrets list demo - Visit your state repo on GitHub and review the recent commit made by Riser. Note that the secret has been encrypted.
- While the secret has been saved, it’s not accessible to your app until it’s deployed. Deploy the docker tag
0.1.2to thedemoenvironment - Once the new deployment is Ready, visit Visit https://testdummy.apps.demo.riser/env. You should see an entry for
MYSECRET
Step 7 - Rollback Deployment #
Riser allows you to route traffic to an old Revision of your Deployment. This provides a true rollback which rolls back all state including the docker tag, your App Config, and your secrets.
Lets say that our last step to configure secrets caused an issue with the App and we don’t have a quick fix that we can apply and “roll forward”. Use the riser rollout command to rollback to a previous revision:
- Use
riser status --all-revisionsto get the previous revision number. - Use
riser rollout demo r${REVISION_NUMBER}:100to route all traffic to the desired revision number - Check the status of your deployment. Once traffic is being routed to the previous revision, visit https://testdummy.apps.demo.riser/env to see all env vars. You should notice that the new secret that was added in the previous step is no longer present.
- Once verified, deploy tag
0.1.1to demo again. - Once the new deployment is Ready, visit https://testdummy.apps.demo.riser/env to see all env vars. You should notice that secret
MYSECRETis present again. Once a secret is bound to your App in a given environment, all future deployments in that environment will contain that secret until it is changed or deleted.
ℹ️ Instead of performing a rollback, you may instead redeploy a previously deployed docker tag (e.g. deploy0.1.1again after deploying0.1.2). This creates a new revision, so changes to yourapp.yamlor secrets are still applied.
Step 8 - Secret Revisions #
Similar to deployments, each secret gets their own revision.
- Save a new value for
mysecretin thedemoenvironment:riser secrets save mysecret NewSecretVal demo - Notice revision in
riser secrets list demo - Deploy the docker tag
0.1.1to thedemoenvironment - Once the new deployment is Ready, visit https://testdummy.apps.demo.riser/env to see all env vars. The secret
MYSECRETshould now have the new value. - Perform another rollback to the previous revision.
- Once the rollback is complete, visit https://testdummy.apps.demo.riser/env to see all env vars. The secret
MYSECRETshould now have the original value.
In Riser, secret revisions are automatically bound to deployment revisions. New deployments will always use the latest value of all secrets for a given environment.
Step 9 - Canary Deployment #
For high availability Apps, a Canary style deployment is recommended:
- Use
riser deploy 0.1.2 demo --manual-rollout. - Wait until your deployment is Ready (Tip:
riser deploytakes a--waitflag, useful for CI servers) - Note that even after the deployment is ready, 0% of traffic is being routed to it
- You may test the new revision using the revision specific URL. For example, if the revision number is 7: https://r7-testdummy.apps.demo.riser/version (Tip: If using
curlwith the--resolveflag don’t forget to change the host in both places, e.g. (curl -k https://r7-testdummy.apps.demo.riser/version --resolve "r7-testdummy.apps.demo.riser:443:${GATEWAY_IP}") - Route 50% of the traffic to the canary. If the current revision number is 6 and the new one is 7:
riser rollout demo r6:50 r7:50 - Check the deployment status. Once the traffic is split 50/50, check the
/versionendpoint a few times to observe the traffic being routed between the two.
Step 10 - Named Deployment #
Sometimes you’d like to test a deployment in the same environment without affecting the existing deployment (e.g. for a pull request).
- Use
riser deploy 0.1.2 demo --name testdummy-pr-1 - Check the deployment status
- Note that a named deployment has no affect on your other deployment
- You can access the named deployment at https://testdummy-pr-1.apps.demo.riser
- Named deployments are no different than your default deployment. Revisions, rollouts, secrets, etc. work the same.
Final Step - Take the Survey #
Thank you for taking the time to explore Riser and provide your feedback. It would be appreciated if you filled out this a brief survey.
Take the Survey!