en.search-data.min.21f5dd60a681a41a2abf8dc74df756747efd95cee55de5905113aaf9607e11b6.js

'use strict';(function(){const indexCfg={cache:true};indexCfg.doc={id:'id',field:['title','content'],store:['title','href','section'],};const index=FlexSearch.create('balance',indexCfg);window.bookSearchIndex=index;index.add({'id':0,'href':'/docs/quickstart/','title':"Quickstart",'section':"Docs",'content':"Quickstart #  The Riser demo allows you to easily experiment with Riser using a local Kubernetes cluster.\nPrerequisites #  Ensure that you have a recent version of the following:\n Docker (Note: just for client tooling - the Docker daemon does not need to be running) Minikube Git CLI Kubectl  You must also have a GitHub account for the state repo. Riser will support other git providers in the future.\nℹ️ These dependencies are specifically for running a local demo of a full Riser stack. A typical app developer only needs the Riser client binary.  ⚠️ Windows Users: A Windows release is available but has not yet been tested. It\u0026rsquo;s recommended that you use the Windows Subsystem for Linux for the Riser CLI.  Demo Installation #   Enable the minikube ingress addon: minikube addons enable ingress Create a minikube cluster. For the best results use the recommended settings: minikube start --cpus=4 --memory=6144 --kubernetes-version=1.17.7. Create a GitHub repo for Riser\u0026rsquo;s state (e.g. https://github.com/your-name/riser-state).  Create a branch named main (Riser allows you to customize the branch name but the demo does not) Riser requires write access to the repo. It is recommended that you use SSH with a GitHub deploy key with write access. Riser supports using HTTPS git URLs with authentication such as GitHub personal access token\u0026rsquo;s as well.   Download the latest Riser CLI for your platform and put it in your path. Ensure that your minikube is started. In a new terminal window, run minikube tunnel. Ensure it establishes the tunnel and let it run in the background. Run riser demo install and follow the instructions.  Things to try #   Use riser apps init to create a minimal app config. Check out the annotated app config for a full list of configuration options. Review the emojivoto microservices example Use riser help or check out the table of contents to explore other help topics.  "});index.add({'id':1,'href':'/docs/concepts/apps/','title':"Apps",'section':"Concepts",'content':"Apps #  An App in Riser represents a stateless workload such as websites, REST APIs, GraphQL, or GRPC style APIs. Riser aims to be compliant with little to no code changes for apps that follow the 12 Factor App methodology.\nCreating an App #  An App is identified by its Name and its Namespace. To create a new App, create a new folder and/or cd into a folder of an existing application and type riser apps init (app name). This will create an app in the default Namespace apps with an initial App Config saved to app.yaml.\n⚠️ You may not change the name or namespace of your App after it is created.  Configuring your App #  The initial App Config contains a couple of TODO\u0026rsquo;s:\n Example initial app.yaml ...  name: demo namespace: apps id: dd707c85-bf6c-48ac-9f13-4d663f3c0885 # TODO: Update to use your docker image registry/repo (without tag) here image: your/image expose: # TODO: Update the container port that gets exposed to the HTTPS gateway containerPort: 8000      image should be set to the registry/repository of your docker image. Do not include the docker tag. expose.containerPort should be set to the port that your app is listening on. Note that your app is exposed over 443 and TLS regardless of what port your app is listening on.  While you may name the App Config any way you like, for convenience the Riser CLI will look for an app.yaml in the current folder. If you choose to name it something else, or if you are in a different folder, commands that require the App Config require passing a -f path/to/app.yaml parameter.\nRiser is opinionated with smart defaults to cover the most common scenarios. As such, you may not need to configure anything else for your App. Nevertheless, you may review the configuration options documented in the fully annotated app.yaml in Github.\nOnce you\u0026rsquo;re app is configured, you\u0026rsquo;re ready to move move in to Deployments\nDeleting an App #  Deleting an App has not yet been implemented.\n"});index.add({'id':2,'href':'/docs/concepts/deployments/','title':"Deployments",'section':"Concepts",'content':"Deployments #  A Deployment in Riser describes the desired state of a deployed App to a given Environment.\nℹ️ A Riser Deployment should not be confused with a Kubernetes Deployment. Any possible relationship with Kubernetes primitives should be treated as an implementation detail.  Creating a Deployment #  The primary mechanism for deploying your App is via the Riser CLI using the riser deploy command from inside of your app folder. Like Kubernetes, Riser works with Docker. Riser does not build or publish Docker images for you. See the Docker section for more details.\nAssuming that you have already created your app and built and published your docker images, deploying an app with Riser is simple:\nriser deploy (docker tag) (targetEnvironment) For example, if your docker tag is v1.0 and your Environment is prod:\nriser deploy v1.0 prod ℹ️ Most users will prefer to trigger a deployment from a CI/CD system instead of manually executing the command. The Riser CLI is a single binary making it easy to integrate with all popular CI/CD systems.  Once the Deployment is complete, you may access it using the URL format: https://{deploymentName}.{namespace}.{riserdomain}. Note that the Deployment name is the same as your App name by default. (e.g. for an app named testdummy in the apps namespace with an Environment configured with the dev.mydomain.net domain: https://testdummy.apps.dev.mydomain.net). See the URL Routing section for more details.\nDeployment Status #  Riser provides an app-centric view of your deployments across all Environments using the riser status command. Its goal is to surface only the most pertinent information regarding the state of your app.\nStatus Columns #   Deployment: The name of the deployment Env: The name of the target Environment Traffic: The percentage of traffic being routed to a particular Deployment in a target Environment Rev: The Revision number Docker Tag: The Docker tag Status: A status representing the state of the deployment:  Ready: The deployment is ready to accept traffic Waiting: The deployment is waiting for an operation to complete Unhealthy: The deployment is not healthy (e.g. can\u0026rsquo;t pull the docker image, health check failed, etc) Unknown: The deployment status is not known   Reason: When applicable, provides a description of the current Status  Additional Details #  To get additional information about a specific Deployment, use riser deployments describe (deploymentName) (targetEnvironment). This view provides a additional details beyond that of riser status and as a result is limited to a specific Deployment in a target Environment.\nRevisions #  A Revision represents an immutable snapshot of your Deployment. A Revision is created whenever a Deployment is created (e.g. via riser deploy). A Revision contains the following state:\n The App Config with any environment overrides applied The docker tag Secrets bound to your App  Docker image. A Revision is assigned a unique revision number for a given Deployment and Environment. This facilitates Traffic Management scenarios such as canary deployments and rollbacks. Note that there is no correlation between revision numbers in different environments or between different Deployment names.\nAutomatic Rollout #  By default, traffic is rolled out automatically when a new Deployment is created:\n A new Revision is created The new Revision is deployed using a Blue Green deployment. At this time no traffic is being routed to the Revision Once determined to be healthy, 100% of traffic is immediately routed to the new Revision After a period of time the old Revision is deemed inactive  Manual Rollout #  While an automatic rollout is sufficient for some use cases, there are reasons to employ a manual rollout:\n Canary Deployments: There is a desire to test the new Deployment on a subset of traffic before doing a full rollout. Rollback: There is a critical problem with a deployment that cannot be quickly fixed or \u0026ldquo;rolled forward\u0026rdquo;  ℹ️ Remember that all operations that affect the state of your app go through Git. As such, manual rollout changes will take a few moments to apply.  Canary Deployments #  A Canary style deployment can be achieved by deploying with the --manual-rollout flag.\nriser deploy (docker tag) (targetEnvironment) --manual-rollout riser status will now show two active Revisions for your Deployment. For example:\nAt this point, the new Revision is not receiving any traffic. In addition to reviewing traditional metrics and logging, you may also access the Revision directly using the URL format: https://r{revNumber}-{deployment}.{namespace}.{riserdomain} (e.g. https://r2-testdummy.apps.dev.mydomain.net). See the URL Routing section for more details.\nYou may now use the riser rollout command to route a percentage of traffic to the new Revision. The following example routes 10% of traffic to a new Revision (#11), and 90% of traffic to the old Revision (#10).\nriser rollout dev r11:10 r10:90 ℹ️ The riser rollout command also supports a single wildcard rule. For example: riser rollout dev r11:10 r10:* is equivalent to the preceding command.  You may rollout the new Revision in as many or little steps as you wish. To route 100% of the traffic to the new Revision, simply specify a single traffic rule. For example:\nriser rollout dev r11:100 ℹ️ While the information in this section implies manual steps, such as validating health metrics and initiating several riser rollout commands, it is encouraged to consider implementing these steps as part of an automated Deployment Pipeline.  Rollback #  A rollback is useful when there is a fatal problem with a Deployment that cannot be quickly fixed or \u0026ldquo;rolled forward\u0026rdquo;. Because a Revision in Riser contains a snapshot of all configuration state, it provides a \u0026ldquo;true rollback\u0026rdquo; of all state related to a Deployment.\nSimilar to a Canary style deployment, you may use the riser rollout command to rollback to a previous Revision. Simply specify the desired revision and route 100% of traffic to it. The following example routes 100% of traffic to Revision #10 in the dev environment:\nriser rollout dev r10:100 ℹ️ You may use the riser status --all-revisions command to show all available revisions.  Garbage Collection #  While this history of each Revision will always be present in the Git state repo, the Revision itself will be garbage collected from the server based on criteria set by the platform operator. Typically at least 10 Revisions will be preserved. Once a Revision is garbage collected it is no longer visible to Riser.\nNamed Deployments #  Sometimes you\u0026rsquo;d like to test a different build of your App without needing a completely separate environment. To accommodate this, Riser supports a naming your deployments. The name of your Deployment must:\n Include your App name as the prefix, followed by a dash, followed by one or more lowercase letters, numbers, or dashes. Must not collide with any other Deployment name regardless of the App or the Environment that a Deployment is deployed to.  Many deployment related operations carry the optional --name flag to specify the name of your deployment. The following example creates a Deployment named testdummy-pr-15 for the testdummy App:\nriser deploy dev 0.1.2 --name testdummy-pr-15 You may access the named Deployment using the URL format: https://{deploymentName}.{namespace}.{riserdomain} (e.g. https://testdummy-pr-15.apps.dev.mydomain.net). See the URL Routing for more details.\nriser status will show the status for all deployments associated with your App. For example:\nSome points to observe:\n A named Deployment gets its own unique Revision number. There is no correlation between revision numbers between different Deployment names. You may control traffic routing via the riser rollout command with the --name parameter. Note that you may not route between deployments with different names.  Deleting a Deployment #  Some deployments, particularly for named deployments, are ephemeral. For example, let\u0026rsquo;s say that your deployment pipeline creates a named deployment for every pull request. You may wish to add a automation to automatically delete the deployment after the pull request is merged. Deleting a deployment is simple:\nriser deployments delete \u0026lt;deploymentName\u0026gt; ❌ Danger Zone! Deleting a Deployment deletes all associated Revisions along with it. You will still be able to review the history in Git, but Riser does not provide any sort of \u0026ldquo;undelete\u0026rdquo; mechanism. You may always create a new Deployment with similar configuration, realizing that there are no guarantees that the Deployment will be in the same state  "});index.add({'id':3,'href':'/docs/concepts/environments/','title':"Environments",'section':"Concepts",'content':"Environments #  An Environment in Riser represents a deployment environment. There is a one-to-one mapping between a Kubernetes cluster and an Environment. Riser has no restrictions on how or what environments you have or how those environments are used.\nCreating an Environment #  An Environment is created when the Riser Controller is installed to a Kubernetes cluster and configured with desired Environment name.\nDeleting an Environment #  Deleting an Environment has not yet been implemented.\n"});index.add({'id':4,'href':'/docs/concepts/namespaces/','title':"Namespaces",'section':"Concepts",'content':"Namespaces #  A Riser Namespace has a one to one correlation with a Kubernetes Namespace. Namespaces provide a scope for names. App names of need to be unique within a Namespace, but not across Namespaces. Most Riser operations do not require specifying a Namespace. The default Namespace in Riser is named apps.\nCreating a Namespace #  Use riser namespaces new (namespace name) to create a new Namespace.\nDeleting a Namespace #  Deleting a Namespace has not yet been implemented.\n"});index.add({'id':5,'href':'/docs/concepts/runtime/','title':"Runtime",'section':"Concepts",'content':"Runtime #  Environment Variables #  The Riser runtime injects environment variables that provide information about the runtime or your app itself.\n   Name Description     RISER_APP The name of the Riser app   RISER_DEPLOYMENT The name of the Riser deployment   RISER_DEPLOYMENT_REVISION The revision number of the Riser deployment   RISER_ENVIRONMENT The name of the Riser environment   RISER_NAMESPACE The name of the Riser namespace    "});index.add({'id':6,'href':'/docs/concepts/secrets/','title':"Secrets",'section':"Concepts",'content':"Secrets #  A Secret allows you to manage the lifecyle of sensitive information inside of Riser. Riser takes advantage of Public Key Infrastructure to provide a mechanism that allows for the secure management of sensitive values within a GitOps environment.\nTo learn more about the architecture of this feature, review the Secrets Internals section.\nℹ️ Other than a brief moment during the encryption phase, Riser does not have access to your Secrets. Riser does not need access to your secrets or your private keys on your Kubernetes clusters.  Saving a Secret #  There are some important considerations to consider when using this feature:\n Secrets are stored per App and per Environment Secrets may not be shared between Apps or Environments For security reasons, there is intentionally no mechanism to read or copy a Secret You should not consider Riser Secrets as the canonical store for sensitive information  Use riser secrets save (name) (plaintextsecret) (targetEnvironment) from inside your app folder to save a secret. For example, to save a postgres URL to the dev environment:\nriser secrets save POSTGRES_URL \u0026#34;postgres://user:s3cr3t@postgres.net/mydb\u0026#34; dev You should now see your secret using the command riser secrets list (environment)\nAccessing Secrets from your App #  Once one or more Secrets are saved to an Environment, they are automatically bound to your App on each subsequent Deployment in that Environment. Secrets are securely bound to your app using environment variables. For example, a Secret named POSTGRES_URL is bound to the environment variable POSTGRES_URL in your app.\nSecret Revisions #  When you wish to update a Secret, simply save a secret with the same name and a new value for the target Environment using riser secrets save.... Like saving a new Secret, the new value is not applied until after a new Deployment in that Environment takes place. Additionally, Riser will assign a revision number to the Secret. The Secret Revision is tied to your Deployment\u0026rsquo;s Revision. This means that if you ever rollback your Deployment that your Secret values will rollback along with it.\nAdvanced Example #  Most of the time it\u0026rsquo;s just as simple as saving a Secret and creating a Deployment. The following is a more complex example where we save multiple revisions of the Secret and rollback our Deployment. Let\u0026rsquo;s start with an App with no Secrets and we wish to save a secret FOO and access it from our code:\nriser secrets save FOO fooval1 dev Current State: The secret has been encrypted and saved in the State Repo, but the environment variable FOO does not exist until we create a new Deployment to the dev Environment.\nriser deploy v1 dev Current State: The environment variable FOO now has the value fooval1 in the dev Environment. The Deployment Revision is 2.\nriser secrets save FOO fooval2 dev Current State: The new secret value has been encrypted and saved in the State Repo. The environment variable FOO will still have the value fooval1 until we create a new Deployment to the dev Environment.\nriser deploy v1 dev ℹ️ It\u0026rsquo;s okay to deploy the same Docker tag multiple times (e.g. v1 in this example). Riser considers all configuration as code, including secrets. Riser will still create a new Deployment Revision even though you are deploying with the same Docker tag.  Current State: The environment variable FOO now has the value fooval2 in the dev Environment. The Deployment Revision is 3.\nWe\u0026rsquo;ve discovered a problem with our App and we\u0026rsquo;ve decided to rollback the Deployment back to Revision 2\nriser rollout dev r2:100 Current State: The environment variable FOO now has the value fooval1 in the dev Environment. The Deployment Revision is 2.\nRiser always uses the most recent Secret Revision for a Deployment, regardless whether or not a rollback ocurred. If we were to redeploy our app again:\nriser deploy v1 dev Current State: The environment variable FOO now has the value fooval2 in the dev Environment. The Deployment Revision is 4.\nℹ️ You never need to worry about the specific Secret Revisions. Riser manages which Deployment Revision maps to which Secret Revision for you so that you don\u0026rsquo;t have to.  Deleting a Secret #  Deleting a Secret has not yet been implemented.\n"});index.add({'id':7,'href':'/docs/concepts/url_routing/','title':"Url Routing",'section':"Concepts",'content':"URL Routing #  Riser offers simple routing for a few common scenarios. The examples on this page assume the following configuration unless otherwise specified:\n Deployment Name: testdummy Namespace: apps Domain name: dev.myplatform.net  Domain Name #  Each Environment can have its own domain name. It is recommended, although not required, to use the same base domain name across all Environments with a subdomain named the same as the Environment name. For example, for the domain name myplatform.net, the dev Environment should have the domain dev.myplatform.net, and the prod Environment should have the domain prod.myplatform.net.\nFor Operators #  Review the Knative docs for setting up a domain in each cluster. Riser reads the Knative configuration in each cluster and maps the domain to the environment. At this time Riser only supports a single domain per Environment.\nExternal URLs #  By default, Apps are exposed externally, meaning outside of the cluster\u0026rsquo;s service mesh. Depending on how your network architecture is set up, this could mean exposing your App to your private network or to the general public (note: See the Vanity URLs section below for additional recommendations on public exposure)\nURL Pattern: https://{deploymentName}.{namespace}.{riserDomain}\nExample: https://testdummy.apps.dev.myplatform.net\nℹ️ The Deployment name is the App name by default  ℹ️ If you do not wish to expose your App externally, set the expose.scope property to cluster in your App Config  Cluster URLs #  The cluster URL is useful if you have an App that takes a dependency on another App in the same Kubernetes cluster. Currently there is a 1:1 relationship between a Riser Environment and a Kubernetes cluster.\nURL Pattern: http://{deploymentName}.{namespace}.svc.cluster.local\nExample: http://testdummy.apps.svc.cluster.local\nℹ️ A future version of Riser may require security policy changes in order to communicate between Apps in different namespaces  Revision URLs #  Riser provides the ability to access a specific Deployment Revision directly.\nURL Pattern: https://r{revisionNumber}-{deploymentName}.{namespace}.{riserDomain} or http://r{revisionNumber}-{deploymentName}.{namespace}.svc.cluster.local\nExample: https://r2-testdummy.apps.dev.myplatform.net\nSee the Revisions section for more details.\nVanity URLs #  Because there are many different approaches to managing URLs and frontend proxies, Riser does not have explicit support for Vanity URls. The following section provides examples of various approaches but is not intended to be exhaustive.\nDNS CNAME #  If your load balancer is accessible to the network in which you plan to expose your app (e.g. the public internet or your company intranet), you may wish to use a simple CNAME record in your DNS server. For example:\ntestdummy.org. CNAME testdummy.apps.prod.myplatform.net. For public websites, you may wish to consider a CDN such as Cloudflare or Akamai.\nReverse Proxies #  Reverse proxies can provide more sophisticated routing scenarios such as additional authentication options, path based routing, etc. Since Riser prescribes the use of Istio, you may consider leveraging it for your routing needs. Alternatively, some find proxies such as Nginx or Kong or better suited to their needs.\n"});index.add({'id':8,'href':'/docs/guidance/docker/','title':"Docker",'section':"Guidance",'content':"Docker #  Since Riser is built on Kubernetes, it uses Docker to package and run your application. Building and publishing your own Docker images is outside the scope of the Riser project. If you\u0026rsquo;re unfamiliar with Docker, you should review the Docker documentation before proceeding with Riser.\nPrivate Registries #  Riser does not yet support pod level ImagePullSecrets. If you have a private registry, you must use one of the following mechanisms:\n If you\u0026rsquo;re using a managed Kubernetes cluster on a popular cloud provider, most provide a registry authentication mechanism which does not require the use of ImagePullSecrets. This is the recommended approach from both a maintainability as well as a security perspective. If you control the Kubernetes cluster, consider configuring the nodes to authenticate with the registry You may also consider attaching credentials to a service account. Note that this must be done for each Kubernetes namespace which requires access to the private registry.  "});index.add({'id':9,'href':'/docs/internals/gitops/','title':"Gitops",'section':"Internals",'content':"GitOps #  Riser is built on the principles of GitOps. Every change that Riser makes happens via a State Repo, a Git repository which holds a versioned account of all Kubernetes state. Whenever you issue a command in Riser (e.g. to make a Deployment), Riser makes a commit to the State Repo with the desired changes on your behalf. Each Kubernetes cluster watches for changes in the GitOps repo and applies those changes on a continuous basis.\nℹ️ You do not need to interact with the State Repo as part of normal Riser operations. The State Repo is useful for auditing (e.g. who changed what and when) and for debugging (e.g. what is the current state of my Deployment)  The State Repo #  Folder Structure #  Riser manages the folder structure of the State Repo for you. This section is useful to help you navigate the State Repo for auditing or debugging purposes, or if you wish to use the State Repo for Kubernetes state that is not managed by Riser.\n⚠️ Riser is the source of truth for all resources managed by Riser. Riser makes no attempt to merge any changes with Riser\u0026rsquo;s desired state and the state of the repo. Do not modify any Riser managed resources in the State Repo.  Annotated Example #  The following is an example of a State Repo with two environments, \u0026ldquo;dev\u0026rdquo; and \u0026ldquo;prod\u0026rdquo;, and an App with a Deployment named \u0026ldquo;testdummy\u0026rdquo; in the \u0026ldquo;apps\u0026rdquo; namespace.\n├── riser-config # \u0026lt;- Configuration used to generate the state. This folder exists for auditing and debugging purposes │ ├── dev # \u0026lt;- The environment │ │ └── apps # \u0026lt;- The namespace │ │ └── testdummy.yaml # \u0026lt;- The App config for \u0026#34;testdummy\u0026#34; │ └── prod # \u0026lt;- The environment │ └── ... # \u0026lt;- Same as \u0026#34;dev\u0026#34; above, but with configuration for the \u0026#34;prod\u0026#34; environment └── state # \u0026lt;- Kubernetes state goes here ├── dev # \u0026lt;- The environment. A Kubernetes cluster (for the \u0026#34;dev\u0026#34; environment) applies all resources from this folder │ └── riser-managed # \u0026lt;- Resources that are managed by Riser. │ ├── apps # \u0026lt;- The namespace │ │ ├── deployments # \u0026lt;- deployment resources │ │ │ ├── testdummy # \u0026lt;- The deployment name │ │ │ │ └── ...*.yaml # \u0026lt;- One or more deployment resource files │ │ └── secrets # \u0026lt;- App encrypted secrets │ │ └── testdummy # \u0026lt;- The app name │ │ └── ...*.yaml # \u0026lt;- One or more secret resource files │ └── namespace.apps.yaml # \u0026lt;- The namespace ya └── prod # \u0026lt;- The environment. A Kubernetes cluster (for the \u0026#34;prod\u0026#34; environment) applies all resources from this folder └── ... # \u0026lt;- Same as \u0026#34;dev\u0026#34; above, but with resources for the \u0026#34;prod\u0026#34; environment riser-config #  The top level riser-config folder is a top level folder that contains all configuration used to generate Kubernetes state for each App, in each Environment, and for each Deployment in that Environment. It contains the final configuration used with any overrides applied. This folder is only used for auditing and debugging purposes. It makes it easy to observe what changes happened in a given environment over time. It also makes it trivial to compare differences between environments. For example, the following command shows the differences between the current final state of the testdummy deployment between the dev and the prod environment.\ndiff -c riser-config/dev/apps/testdummy.yaml riser-config/prod/apps/testdummy.yaml With this approach, there is no need to do any mental gymnastics with template variables or complicated overlays to determine your App\u0026rsquo;s configuration.\nstate #  The top level state folder contains all resources that represent state in Kubernetes. Each Environment has its own sub folder which contains the resources that are continuously applied to the Kubernetes cluster. The riser-managed folder container resources that are strictly managed by Riser. You should treat this as a readonly folder. If you have non Riser resources that you would also like to manage via GitOps, you may create a sibling folder and manage those resources as you wish.\n"});index.add({'id':10,'href':'/docs/internals/secrets/','title':"Secrets",'section':"Internals",'content':"Secrets #  Riser Secrets is built on Bitnami Sealed Secrets, a project which takes advantage of Public Key Infrastructure to provide a mechanism that allows for the secure management of sensitive values within a GitOps environment.\nArchitecture #  The Riser Controller watches the public key on each cluster and keeps the Riser Server up-to-date. Riser never needs access to the private keys. Riser only has access to the plaintext secret in memory for the brief moment of time that is necessary to encrypt the secret with the public key. Private keys, including rotation and archival, are managed by the Sealed Secrets controller. See the Sealed Secrets documentation for more details. There is work in progress to support AWS KMS as well as a general plug-in architecture for other key management solutions in the future.\n"});index.add({'id':11,'href':'/docs/workshops/v1/','title':"V1",'section':"Workshops",'content':"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.\nℹ️ 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\u0026rsquo;re development environment is setup to participate. Please ensure the following:\n Ensure that you have a recent version of the following  Docker Minikube Git CLI Kubectl   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\u0026rsquo;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.\n 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, \u0026ldquo;Try out the testdummy app\u0026rdquo;, as this is covered later in Workshop. Optional: If you don\u0026rsquo;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\u0026rsquo;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.\n 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\u0026rsquo;s name and namespace so that you don\u0026rsquo;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 \u0026quot;testdummy.apps.demo.riser:443:${GATEWAY_IP}\u0026quot;, 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:\nname: testdummy # ...omitted... env: MEANING: 42 # This allows us to view all env vars at the /env endpoint TESTDUMMY_ENABLE_ENV: \u0026quot;true\u0026quot;  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.\n 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\u0026rsquo;s not accessible to your app until it\u0026rsquo;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.\nLets say that our last step to configure secrets caused an issue with the App and we don\u0026rsquo;t have a quick fix that we can apply and \u0026ldquo;roll forward\u0026rdquo;. Use the riser rollout command to rollback to a previous revision:\n 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.\n 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.\nStep 9 - Canary Deployment #  For high availability Apps, a Canary style deployment is recommended:\n 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\u0026rsquo;t forget to change the host in both places, e.g. (curl -k https://r7-testdummy.apps.demo.riser/version --resolve \u0026quot;r7-testdummy.apps.demo.riser:443:${GATEWAY_IP}\u0026quot;) 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\u0026rsquo;d like to test a deployment in the same environment without affecting the existing deployment (e.g. for a pull request).\n 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.   Stuck? ↕   If you don\u0026rsquo;t have a local DNS server, don\u0026rsquo;t forget to change both the URL and the --resolve flag to reflect testdummy-pr-1: curl -k https://testdummy-pr-1.apps.demo.riser --resolve \u0026quot;testdummy-pr-1.apps.demo.riser:443:${GATEWAY_IP}\u0026quot;. Use riser demo status to display your gateway IP again.     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.\nTake the Survey!  "});index.add({'id':15,'href':'/docs/internals/','title':"Internals",'section':"Docs",'content':"This section provides details about the inner workings of Riser. Knowledge of Riser internals is not required for the typical usage of Riser.\n"});index.add({'id':16,'href':'/docs/operations/','title':"Operations",'section':"Docs",'content':"This section provides details about operating Riser. Knowledge of Riser operations is not required for the typical usage of Riser.\nRiser is an experimental project that is not yet recommended for production use. This section will be developed as Riser matures. The recommended way to test Riser is to use riser demo install against an existing Kubernetes cluster as instructed in the Quickstart. This configures Riser as well as all operational components such as Knative and Istio.\nFor the adventurous, the riser-server repo contains some base yaml for a Riser development environment that could be used as a basis for building your own installation.\n"});})();