V1

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-context is 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 install and 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_IP to your gateway IP: e.g. export GATEWAY_IP=10.1.2.3. This will be used later for curl commands.

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)
    • cd into the directory.
    • You should run all future riser commands from this directory.
  • Create and initialize your app: riser apps init testdummy
    • Edit the TODOs in app.yaml where necessary
    • The Docker image is tshak/testdummy. Do not specify the docker tag.
    • testdummy already listens on port 8000
  • Verify that your app exists in riser apps list
ℹ️ Riser reads the app.yaml in 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 the riser command.

Step 3 - Your first deployment #

  • Check the status via riser status
  • Deploy the docker tag 0.1.1 to the demo environment: 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}", where GATEWAY_IP is 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 status to display your gateway IP again if required.
  • Visit your state repo on GitHub and review the commits made by Riser
    • The /riser-config folder contains the Riser config used to generate the state
    • The /state/demo/riser-managed folder contains all Riser managed state for the demo environment

Step 4 - Your next deployment #

  • Verify the version endpoint of the testdummy at https://testdummy.apps.demo.riser/version returns 0.1.1
  • Deploy the docker tag 0.1.2 to the demo environment
  • Check the status of your deployment
  • Once the new deployment is Ready, verify the version endpoint

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.2 of the demo environment
  • 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 demo environment: 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.2 to the demo environment
  • 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-revisions to get the previous revision number.
  • Use riser rollout demo r${REVISION_NUMBER}:100 to 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.1 to 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 MYSECRET is 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. deploy 0.1.1 again after deploying 0.1.2). This creates a new revision, so changes to your app.yaml or secrets are still applied.

Step 8 - Secret Revisions #

Similar to deployments, each secret gets their own revision.

  • Save a new value for mysecret in the demo environment: riser secrets save mysecret NewSecretVal demo
  • Notice revision in riser secrets list demo
  • Deploy the docker tag 0.1.1 to the demo environment
  • Once the new deployment is Ready, visit https://testdummy.apps.demo.riser/env to see all env vars. The secret MYSECRET should 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 MYSECRET should 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 deploy takes a --wait flag, 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 curl with the --resolve flag 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 /version endpoint 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!