From 309427d435f58a9ea909a0296055181e2d05371f Mon Sep 17 00:00:00 2001 From: Naomi Seyfer Date: Mon, 17 Sep 2018 14:58:19 -0700 Subject: [PATCH 01/11] Change normative example from pinned to release mode --- docs/spec/normative_examples.md | 215 +++++++++++++++++--------------- 1 file changed, 112 insertions(+), 103 deletions(-) diff --git a/docs/spec/normative_examples.md b/docs/spec/normative_examples.md index 50f2ea169c05..a25096a0d847 100644 --- a/docs/spec/normative_examples.md +++ b/docs/spec/normative_examples.md @@ -9,8 +9,8 @@ Examples in this section illustrate: * [Automatic rollout of a new Revision to an existing Service with a pre-built container](#1-automatic-rollout-of-a-new-revision-to-existing-service---pre-built-container) * [Creating a new Service with a pre-built container](#2-creating-a-new-service-with-a-pre-built-container) -* [Configuration changes and manual rollout - options](#3-manual-rollout-of-a-new-revision---config-change-only) +* [Configuration changes and managed rollout + options](#3-managed-rollout-of-a-new-revision---config-change-only) * [Creating a revision from source](#4-deploy-a-revision-from-source) * [Creating a function from source](#5-deploy-a-function) @@ -24,7 +24,9 @@ represent final CLI design. ## 1) Automatic rollout of a new Revision to existing Service - pre-built container **_Scenario_**: User deploys a new revision to an existing service -with a new container image, rolling out automatically to 100% +with a new container image, rolling out automatically to 100%. + +This corresponds to the service in `runLatest` mode. ```console $ knative deploy --service my-service @@ -32,7 +34,7 @@ $ knative deploy --service my-service ✓ Starting ✓ Promoting Done. - Deployed to https://my-service.default.mydomain.com + Deployed revision v3 to https://my-service.default.mydomain.com ``` **Steps**: @@ -303,7 +305,7 @@ illustrates. This is the most straightforward scenario that many Knative Serving customers are expected to use, and is consistent with the experience of deploying code that is rolled out immediately. A Route may also directly reference a Revision, which is shown in -[example 3](#3-manual-rollout-of-a-new-revision---config-change-only). +[example 3](#3-managed-rollout-of-a-new-revision---config-change-only). The example shows the POST calls issued by the client, followed by several GET calls to illustrate each step in the reconciliation @@ -514,17 +516,26 @@ status: ``` -## 3) Manual rollout of a new Revision - config change only +## 3) Managed rollout of a new Revision - config change only -**_Scenario_**: User updates configuration with new runtime arguments - (env var change) to an existing service, tests the revision, then - proceeds with a manually controlled rollout to 100% +**_Scenario_**: User updates configuration with new runtime arguments (env var + change) to an existing service, tests the revision, then proceeds with a + human-controlled rollout to 100% -```console -$ knative rollout --service my-service strategy manual +``` +$ knative rollout --service my-service strategy release + +$ knative revisions list --service my-service +Name Traffic Id Date Deployer Git SHA +current 100% v2 2018-01-18 20:34 user1 a6f92d1 + v1 2018-01-17 10:32 user1 33643fc $ knative deploy --service my-service --env HELLO="blurg" [...] +Deployed revision v3 to https://latest.my-service.default.mydomain.com +You can begin rolling out this revision with [knative rollout begin v3] + +$ knative rollout begin v3 $ knative revisions list --service my-service Name Traffic Id Date Deployer Git SHA @@ -532,27 +543,33 @@ next 0% v3 2018-01-19 12:16 user1 a6f92d1 current 100% v2 2018-01-18 20:34 user1 a6f92d1 v1 2018-01-17 10:32 user1 33643fc -$ knative rollout next percent 5 +$ knative rollout percent 5 [...] -$ knative rollout next percent 50 +$ knative rollout percent 50 [...] $ knative rollout finish [...] $ knative revisions list --service my-service Name Traffic Id Date Deployer Git SHA -current,next 100% v3 2018-01-19 12:16 user1 a6f92d1 +current 100% v3 2018-01-19 12:16 user1 a6f92d1 v2 2018-01-18 20:34 user1 a6f92d1 v1 2018-01-17 10:32 user1 33643fc ``` **Steps**: -* Update the Service to switch from `runLatest` to `pinned` strategy. +* Update the Service to switch from a `runLatest` strategy to a `release` + strategy. * Update the Service with the new configuration (env var). -* Update the Service to address the new Revision. +* Update the Service include the new revision in its revision list, which makes + it address the new Revision as `next`. + +* Adjust the `percentRollout` controlling the traffic on `next`. + +* Complete the rollout so the new revision is `current`. **Results:** @@ -562,20 +579,20 @@ current,next 100% v3 2018-01-19 12:16 user1 a6f92d1 completing the rollout, the next revision is now the current revision. -![Manual rollout](images/manual_rollout.png) +![Rollout mode](images/manual_rollout.png) -In the previous examples, the Service automatically made changes to -the configuration (newly created Revision) routable when they became -ready. While this pattern is useful for many scenarios such as -functions-as-a-service and simple development flows, the Service can -also reference Revisions directly in `pinned` mode to route traffic to -a specific Revision, which is suitable for rolling back a service to a known-good state. manually controlling -rollouts, i.e. testing a new revision prior to serving traffic. (Note: -see [Appendix B](complex_examples.md) for a semi-automatic variation -of manual rollouts). +In the previous examples, the Service automatically made changes to the +configuration (newly created Revision) routable when they became ready. While +this pattern is useful for many scenarios such as functions-as-a-service and +simple development flows, the Service can also reference Revisions directly in +`release` mode to route traffic to two specific revisions: the revision that's +been running, and the new revision the user would like test, or canary a portion +of traffic to, prior to rolling out entirely. This mode is also useful to roll +back to a known-good previous revision. (Note: see [Appendix +B](complex_examples.md) for a semi-automatic variation of managed rollouts). -The client updates the service to pin the current revision: +The client updates the service to switch to release mode. ```http PUT /apis/serving.knative.dev/v1alpha1/namespaces/default/services/my-service @@ -587,13 +604,13 @@ kind: Service metadata: name: my-service spec: - pinned: - revisionName: def + relase: + revisions: [def] configuration: # Copied from spec.runLatest.configuration - revisionTemplate: # template for building Revision + revisionTemplate: spec: container: - image: gcr.io/... # new image + image: gcr.io/... ``` This causes the Route to be updated to pin traffic the specified @@ -610,14 +627,13 @@ kind: Route metadata: name: my-service spec: - rollout: - traffic: - - revisionName: def - name: current # addressable as current.my-service.default.mydomain.com - percent: 100 - - configurationName: my-service # LatestReadyRevision of my-service - name: next # addressable as next.my-service.default.mydomain.com - percent: 0 # no traffic yet + release: + revisions: [def] + configuration: # Copied from spec.runLatest.configuration + revisionTemplate: + spec: + container: + image: gcr.io/... ``` Next, the service is updated with the new variables, which causes the @@ -634,39 +650,20 @@ kind: Service metadata: name: my-service spec: - pinned: - configuration: # Copied from spec.runLatest.configuration - revisionTemplate: # template for building Revision + release: + configuration: + revisionTemplate: spec: container: env: # k8s-style strategic merge patch, updating a single list value + # Image etc. do not change - name: HELLO value: blurg # changed value ``` -As in the previous example, the configuration is updated to trigger -the creation of a new revision: - -```http -PATCH /apis/serving.knative.dev/v1alpha1/namespaces/default/configurations/my-service -``` - -```yaml -apiVersion: serving.knative.dev/v1alpha1 -kind: Configuration -metadata: - name: my-service -spec: - revisionTemplate: - spec: - container: - env: # k8s-style strategic merge patch, updating a single list value - - name: HELLO - value: blurg # changed value -``` - -A new revision `ghi` is created that has the same code as the previous -revision `def`, but different config: +As in the previous example, the configuration is updated to trigger the creation +of a new revision, and a new revision `ghi` is created that has the same code as +the previous revision `def`, but different config: ```http GET /apis/serving.knative.dev/v1alpha1/namespaces/default/revisions/ghi @@ -696,10 +693,41 @@ status: Even when ready, the new revision does not automatically start serving traffic, as the route was pinned to revision `def`. -Once the new revision is ready, the route will update the `next` name -to point to the revision `ghi`. The new revision will still not -receive any traffic by default, but can be accessed for testing, -verification, etc. +The user can then begin the rollout of revision ghi: + +```http +PATCH /apis/serving.knative.dev/v1alpha1/namespaces/default/services/my-service +``` +```yaml +apiVersion: serving.knative.dev/v1alpha1 +kind: Service +metadata: + name: my-service +spec: + release: + revisions: [def, ghi] + rolloutPercent: 0 +``` + +This makes the route update the `next` name to point to the revision `ghi`. (The +list of revisions can contain one or two items. If two, the first is `current` +and the latter is `next`) The new revision will still not receive any traffic, +but can be accessed for testing, verification, etc. + +To put traffic on `ghi`, the user can adjust `rolloutPercent`: + +```http +PATCH /apis/serving.knative.dev/v1alpha1/namespaces/default/services/my-service +``` +```yaml +apiVersion: serving.knative.dev/v1alpha1 +kind: Service +metadata: + name: my-service +spec: + release: + rolloutPercent: 5 +``` ```http GET /apis/serving.knative.dev/v1alpha1/namespaces/default/routes/my-service @@ -724,18 +752,20 @@ status: traffic: - revisionName: def name: current # addressable as current.my-service.default.mydomain.com - percent: 100 + percent: 95 - revisionName: ghi name: next # addressable as next.my-service.default.mydomain.com + percent: 5 + - configurationName: my-service # LatestReadyRevision of my-service + name: latest percent: 0 conditions: - type: Ready status: True ``` -After testing the new revision at -`next.my-service.default.mydomain.com`, it can be promoted to live by -updating the service to pin `ghi` as the new revision. +After testing the new revision at `next.my-service.default.mydomain.com`, it can +be promoted to live by updating the service to pin `ghi` as the new revision. ```http PATCH /apis/serving.knative.dev/v1alpha1/namespaces/default/services/my-service @@ -747,36 +777,15 @@ kind: Service metadata: name: my-service spec: - pinned: - revisionname: ghi + release: + revisions: [ghi] ``` -This causes the service to update the route to assign. - -```http -PATCH /apis/serving.knative.dev/v1alpha1/namespaces/default/routes/my-service -``` - -```yaml -apiVersion: serving.knative.dev/v1alpha1 -kind: route -metadata: - name: my-service -spec: - rollout: - traffic: - - revisionName: ghi - name: current - percent: 100 - - configurationName: my-service # LatestReadyRevision of my-service - name: next - percent: 0 -``` +This causes the service to update the route to assign 100% of traffic to ghi. -Once the update has been completed, if the latest ready revision is -the same as the pinned revision, the names `current` and `next` will -point to the same revision. Both names are left in place so that -`next.my-service.default.mydomain.com` is always addressable. +Once the update has been completed, if the latest ready revision is the same as +the pinned revision, the names `current` and `latest` will point to the same +revision. The name `next` is inactive until you're rolling out a revision again. ```http GET /apis/serving.knative.dev/v1alpha1/namespaces/default/routes/my-service @@ -790,11 +799,11 @@ metadata: spec: rollout: traffic: - - revisionName: ghi # update for the next rollout, current = next + - revisionName: ghi name: current percent: 100 - - revisionName: ghi # optional: leave next as also referring to ghi - name: next + - revisionName: ghi + name: latest percent: 0 status: domain: my-service.default.mydomain.com From c4e2626e51c5fd4dccaa3a2908ac948f15305209 Mon Sep 17 00:00:00 2001 From: Naomi Seyfer Date: Mon, 17 Sep 2018 15:12:19 -0700 Subject: [PATCH 02/11] Proofread and expand --- docs/spec/normative_examples.md | 53 ++++++++++++++++++++++----------- 1 file changed, 36 insertions(+), 17 deletions(-) diff --git a/docs/spec/normative_examples.md b/docs/spec/normative_examples.md index a25096a0d847..3710cbe31ca4 100644 --- a/docs/spec/normative_examples.md +++ b/docs/spec/normative_examples.md @@ -516,17 +516,17 @@ status: ``` -## 3) Managed rollout of a new Revision - config change only +## 3) Managed release of a new Revision - config change only **_Scenario_**: User updates configuration with new runtime arguments (env var change) to an existing service, tests the revision, then proceeds with a - human-controlled rollout to 100% + human-controlled rollout to 100%. ``` $ knative rollout --service my-service strategy release $ knative revisions list --service my-service -Name Traffic Id Date Deployer Git SHA +Route Traffic Id Date Deployer Git SHA current 100% v2 2018-01-18 20:34 user1 a6f92d1 v1 2018-01-17 10:32 user1 33643fc @@ -538,20 +538,27 @@ You can begin rolling out this revision with [knative rollout begin v3] $ knative rollout begin v3 $ knative revisions list --service my-service -Name Traffic Id Date Deployer Git SHA +Route Traffic Id Date Deployer Git SHA next 0% v3 2018-01-19 12:16 user1 a6f92d1 current 100% v2 2018-01-18 20:34 user1 a6f92d1 v1 2018-01-17 10:32 user1 33643fc $ knative rollout percent 5 [...] + +$ knative revisions list --service my-service +Route Traffic Id Date Deployer Git SHA +next 5% v3 2018-01-19 12:16 user1 a6f92d1 +current 100% v2 2018-01-18 20:34 user1 a6f92d1 + v1 2018-01-17 10:32 user1 33643fc + $ knative rollout percent 50 [...] $ knative rollout finish [...] $ knative revisions list --service my-service -Name Traffic Id Date Deployer Git SHA +Route Traffic Id Date Deployer Git SHA current 100% v3 2018-01-19 12:16 user1 a6f92d1 v2 2018-01-18 20:34 user1 a6f92d1 v1 2018-01-17 10:32 user1 33643fc @@ -562,7 +569,7 @@ current 100% v3 2018-01-19 12:16 user1 a6f92d1 * Update the Service to switch from a `runLatest` strategy to a `release` strategy. -* Update the Service with the new configuration (env var). +* Update the Service with the new configuration (env var). * Update the Service include the new revision in its revision list, which makes it address the new Revision as `next`. @@ -573,11 +580,11 @@ current 100% v3 2018-01-19 12:16 user1 a6f92d1 **Results:** -* The system creates the new revision from the configuration, - addressable at next.my-service... (by convention), but traffic is - not routed to it until the percentage is manually ramped up. Upon - completing the rollout, the next revision is now the current - revision. +* The system creates the new revision from the configuration, addressable at + `latest.my-service...` (by convention), but traffic is not routed to it until + the rollout to that revision is begun (which markes it as + `next.my-service...`) and the percentage is manually ramped up. Upon + completing the rollout, the next revision is now the current revision. ![Rollout mode](images/manual_rollout.png) @@ -691,7 +698,9 @@ status: ``` Even when ready, the new revision does not automatically start serving -traffic, as the route was pinned to revision `def`. +production traffic, as the route was pinned to revision `def`. It will, however, +be optionally accessible under the name `latest.my-service...` for initial +manual testing. The user can then begin the rollout of revision ghi: @@ -712,7 +721,8 @@ spec: This makes the route update the `next` name to point to the revision `ghi`. (The list of revisions can contain one or two items. If two, the first is `current` and the latter is `next`) The new revision will still not receive any traffic, -but can be accessed for testing, verification, etc. +but can be accessed for testing, verification, etc under the +`next.my-service...` name. To put traffic on `ghi`, the user can adjust `rolloutPercent`: @@ -743,10 +753,13 @@ spec: traffic: - revisionName: def name: current # addressable as current.my-service.default.mydomain.com - percent: 100 + percent: 95 + - revisionName: ghi + name: next # addressable as next.my-service.default.mydomain.com + percent: 5 - configurationName: my-service # LatestReadyRevision of my-service - name: next # addressable as next.my-service.default.mydomain.com - percent: 0 # no traffic yet + name: latest # addressable as latest.my-service.default.mydomain.com + percent: 0 # no direct traffic ever. status: domain: my-service.default.mydomain.com traffic: @@ -765,7 +778,8 @@ status: ``` After testing the new revision at `next.my-service.default.mydomain.com`, it can -be promoted to live by updating the service to pin `ghi` as the new revision. +be promoted to a fully-rolled-out `current` revision by updating the service to +list only `ghi` in the revision list. ```http PATCH /apis/serving.knative.dev/v1alpha1/namespaces/default/services/my-service @@ -787,6 +801,11 @@ Once the update has been completed, if the latest ready revision is the same as the pinned revision, the names `current` and `latest` will point to the same revision. The name `next` is inactive until you're rolling out a revision again. +Note that throughout this whole process, `latest` remains pointing to the latest +ready revision of the service. This allows your team to continue to pre-check +and validate new release candidates even while a rollout is in progress between +a validated release candidate and the previous release. + ```http GET /apis/serving.knative.dev/v1alpha1/namespaces/default/routes/my-service ``` From cab1e7eea99caf3ca2babc4c1f89aafc42118a06 Mon Sep 17 00:00:00 2001 From: Naomi Seyfer Date: Mon, 17 Sep 2018 16:28:19 -0700 Subject: [PATCH 03/11] Talk about a safety belt --- docs/spec/normative_examples.md | 50 ++++++++++++++++++++------------- 1 file changed, 30 insertions(+), 20 deletions(-) diff --git a/docs/spec/normative_examples.md b/docs/spec/normative_examples.md index 3710cbe31ca4..57bd1796b5c9 100644 --- a/docs/spec/normative_examples.md +++ b/docs/spec/normative_examples.md @@ -526,42 +526,48 @@ status: $ knative rollout --service my-service strategy release $ knative revisions list --service my-service -Route Traffic Id Date Deployer Git SHA -current 100% v2 2018-01-18 20:34 user1 a6f92d1 - v1 2018-01-17 10:32 user1 33643fc +Route Traffic Id Date Deployer Git SHA +current,latest 100% v2 2018-01-18 20:34 user1 a6f92d1 + v1 2018-01-17 10:32 user1 33643fc $ knative deploy --service my-service --env HELLO="blurg" [...] Deployed revision v3 to https://latest.my-service.default.mydomain.com You can begin rolling out this revision with [knative rollout begin v3] -$ knative rollout begin v3 +$ knative revisions list --service my-service +Route Traffic Id Date Deployer Git SHA +latest 0% v3 2018-01-19 12:16 user1 a6f92d1 +current 100% v2 2018-01-18 20:34 user1 a6f92d1 + v1 2018-01-17 10:32 user1 33643fc + +$ knative release begin v3 $ knative revisions list --service my-service -Route Traffic Id Date Deployer Git SHA -next 0% v3 2018-01-19 12:16 user1 a6f92d1 -current 100% v2 2018-01-18 20:34 user1 a6f92d1 - v1 2018-01-17 10:32 user1 33643fc +Route Traffic Id Date Deployer Git SHA +next,latest 0% v3 2018-01-19 12:16 user1 a6f92d1 +current 100% v2 2018-01-18 20:34 user1 a6f92d1 + v1 2018-01-17 10:32 user1 33643fc -$ knative rollout percent 5 +$ knative release percent 5 [...] $ knative revisions list --service my-service -Route Traffic Id Date Deployer Git SHA -next 5% v3 2018-01-19 12:16 user1 a6f92d1 -current 100% v2 2018-01-18 20:34 user1 a6f92d1 - v1 2018-01-17 10:32 user1 33643fc +Route Traffic Id Date Deployer Git SHA +next,latest 5% v3 2018-01-19 12:16 user1 a6f92d1 +current 100% v2 2018-01-18 20:34 user1 a6f92d1 + v1 2018-01-17 10:32 user1 33643fc -$ knative rollout percent 50 +$ knative release percent 50 [...] -$ knative rollout finish +$ knative release finish [...] $ knative revisions list --service my-service -Route Traffic Id Date Deployer Git SHA -current 100% v3 2018-01-19 12:16 user1 a6f92d1 - v2 2018-01-18 20:34 user1 a6f92d1 - v1 2018-01-17 10:32 user1 33643fc +Route Traffic Id Date Deployer Git SHA +current,latest 100% v3 2018-01-19 12:16 user1 a6f92d1 + v2 2018-01-18 20:34 user1 a6f92d1 + v1 2018-01-17 10:32 user1 33643fc ``` **Steps**: @@ -569,7 +575,7 @@ current 100% v3 2018-01-19 12:16 user1 a6f92d1 * Update the Service to switch from a `runLatest` strategy to a `release` strategy. -* Update the Service with the new configuration (env var). +* Update the Service with the new configuration (env var). * Update the Service include the new revision in its revision list, which makes it address the new Revision as `next`. @@ -724,6 +730,10 @@ and the latter is `next`) The new revision will still not receive any traffic, but can be accessed for testing, verification, etc under the `next.my-service...` name. +An admission hook prevents changing `revisions` without also setting +`rolloutPercent`, if `rolloutPercent` is nonzero. This prevents you from +accidentally changing what you're releasing out mid-release. + To put traffic on `ghi`, the user can adjust `rolloutPercent`: ```http From 5db063b80dcee9eb898ee23de5575d2feff263c0 Mon Sep 17 00:00:00 2001 From: Naomi Seyfer Date: Mon, 17 Sep 2018 16:31:22 -0700 Subject: [PATCH 04/11] consistency in revision names --- docs/spec/normative_examples.md | 44 ++++++++++++++++----------------- 1 file changed, 22 insertions(+), 22 deletions(-) diff --git a/docs/spec/normative_examples.md b/docs/spec/normative_examples.md index 57bd1796b5c9..4fa407028118 100644 --- a/docs/spec/normative_examples.md +++ b/docs/spec/normative_examples.md @@ -526,37 +526,37 @@ status: $ knative rollout --service my-service strategy release $ knative revisions list --service my-service -Route Traffic Id Date Deployer Git SHA -current,latest 100% v2 2018-01-18 20:34 user1 a6f92d1 - v1 2018-01-17 10:32 user1 33643fc +Route Traffic Id Date Deployer Git SHA +current,latest 100% def 2018-01-18 20:34 user1 a6f92d1 + abc 2018-01-17 10:32 user1 33643fc $ knative deploy --service my-service --env HELLO="blurg" [...] -Deployed revision v3 to https://latest.my-service.default.mydomain.com -You can begin rolling out this revision with [knative rollout begin v3] +Deployed revision ghi to https://latest.my-service.default.mydomain.com +You can begin rolling out this revision with [knative rollout begin ghi] $ knative revisions list --service my-service -Route Traffic Id Date Deployer Git SHA -latest 0% v3 2018-01-19 12:16 user1 a6f92d1 -current 100% v2 2018-01-18 20:34 user1 a6f92d1 - v1 2018-01-17 10:32 user1 33643fc +Route Traffic Id Date Deployer Git SHA +latest 0% ghi 2018-01-19 12:16 user1 a6f92d1 +current 100% def 2018-01-18 20:34 user1 a6f92d1 + abc 2018-01-17 10:32 user1 33643fc -$ knative release begin v3 +$ knative release begin ghi $ knative revisions list --service my-service -Route Traffic Id Date Deployer Git SHA -next,latest 0% v3 2018-01-19 12:16 user1 a6f92d1 -current 100% v2 2018-01-18 20:34 user1 a6f92d1 - v1 2018-01-17 10:32 user1 33643fc +Route Traffic Id Date Deployer Git SHA +next,latest 0% ghi 2018-01-19 12:16 user1 a6f92d1 +current 100% def 2018-01-18 20:34 user1 a6f92d1 + abc 2018-01-17 10:32 user1 33643fc $ knative release percent 5 [...] $ knative revisions list --service my-service -Route Traffic Id Date Deployer Git SHA -next,latest 5% v3 2018-01-19 12:16 user1 a6f92d1 -current 100% v2 2018-01-18 20:34 user1 a6f92d1 - v1 2018-01-17 10:32 user1 33643fc +Route Traffic Id Date Deployer Git SHA +next,latest 5% ghi 2018-01-19 12:16 user1 a6f92d1 +current 100% def 2018-01-18 20:34 user1 a6f92d1 + abc 2018-01-17 10:32 user1 33643fc $ knative release percent 50 [...] @@ -564,10 +564,10 @@ $ knative release finish [...] $ knative revisions list --service my-service -Route Traffic Id Date Deployer Git SHA -current,latest 100% v3 2018-01-19 12:16 user1 a6f92d1 - v2 2018-01-18 20:34 user1 a6f92d1 - v1 2018-01-17 10:32 user1 33643fc +Route Traffic Id Date Deployer Git SHA +current,latest 100% ghi 2018-01-19 12:16 user1 a6f92d1 + def 2018-01-18 20:34 user1 a6f92d1 + abc 2018-01-17 10:32 user1 33643fc ``` **Steps**: From 73a3537320b5c19fe955145c148a235bbaf639fb Mon Sep 17 00:00:00 2001 From: Naomi Seyfer Date: Mon, 17 Sep 2018 16:33:44 -0700 Subject: [PATCH 05/11] correct last route spec --- docs/spec/normative_examples.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/spec/normative_examples.md b/docs/spec/normative_examples.md index 4fa407028118..092093c0a870 100644 --- a/docs/spec/normative_examples.md +++ b/docs/spec/normative_examples.md @@ -831,7 +831,7 @@ spec: - revisionName: ghi name: current percent: 100 - - revisionName: ghi + - configurationName: my-service # LatestReadyRevision of my-service name: latest percent: 0 status: @@ -840,8 +840,8 @@ status: - revisionName: ghi name: current # addressable as current.my-service.default.mydomain.com percent: 100 - - revisionName: ghi - name: next # addressable as next.my-service.default.mydomain.com + - configurationName: my-service + name: latest # addressable as latest.my-service.default.mydomain.com percent: 0 conditions: - type: Ready From b03d207e61e6167c08596a3c636a55ca579db547 Mon Sep 17 00:00:00 2001 From: Naomi Seyfer Date: Wed, 19 Sep 2018 15:08:28 -0700 Subject: [PATCH 06/11] Respond to some comments; add rollback --- docs/spec/normative_examples.md | 79 +++++++++++++++++++++++++-------- 1 file changed, 61 insertions(+), 18 deletions(-) diff --git a/docs/spec/normative_examples.md b/docs/spec/normative_examples.md index 092093c0a870..3e776eb39f4a 100644 --- a/docs/spec/normative_examples.md +++ b/docs/spec/normative_examples.md @@ -10,9 +10,10 @@ Examples in this section illustrate: pre-built container](#1-automatic-rollout-of-a-new-revision-to-existing-service---pre-built-container) * [Creating a new Service with a pre-built container](#2-creating-a-new-service-with-a-pre-built-container) * [Configuration changes and managed rollout - options](#3-managed-rollout-of-a-new-revision---config-change-only) -* [Creating a revision from source](#4-deploy-a-revision-from-source) -* [Creating a function from source](#5-deploy-a-function) + options](#3-managed-release-of-a-new-revision---config-change-only) +* [Roll back to a known-good revision](#4-roll-back-to-a-known-good-revision) +* [Creating a revision from source](#5-deploy-a-revision-from-source) +* [Creating a function from source](#6-deploy-a-function) Note that these API operations are identical for both app and function based services. (to see the full resource definitions, see the @@ -305,7 +306,7 @@ illustrates. This is the most straightforward scenario that many Knative Serving customers are expected to use, and is consistent with the experience of deploying code that is rolled out immediately. A Route may also directly reference a Revision, which is shown in -[example 3](#3-managed-rollout-of-a-new-revision---config-change-only). +[example 3](#3-managed-release-of-a-new-revision---config-change-only). The example shows the POST calls issued by the client, followed by several GET calls to illustrate each step in the reconciliation @@ -523,7 +524,7 @@ status: human-controlled rollout to 100%. ``` -$ knative rollout --service my-service strategy release +$ knative release --service my-service strategy release $ knative revisions list --service my-service Route Traffic Id Date Deployer Git SHA @@ -541,7 +542,7 @@ latest 0% ghi 2018-01-19 12:16 user1 a6f92d1 current 100% def 2018-01-18 20:34 user1 a6f92d1 abc 2018-01-17 10:32 user1 33643fc -$ knative release begin ghi +$ knative release --service my-service begin ghi $ knative revisions list --service my-service Route Traffic Id Date Deployer Git SHA @@ -558,9 +559,9 @@ next,latest 5% ghi 2018-01-19 12:16 user1 a6f92d1 current 100% def 2018-01-18 20:34 user1 a6f92d1 abc 2018-01-17 10:32 user1 33643fc -$ knative release percent 50 +$ knative release --service my-service percent 50 [...] -$ knative release finish +$ knative release --service my-service finish [...] $ knative revisions list --service my-service @@ -592,7 +593,7 @@ current,latest 100% ghi 2018-01-19 12:16 user1 a6f92d1 `next.my-service...`) and the percentage is manually ramped up. Upon completing the rollout, the next revision is now the current revision. -![Rollout mode](images/manual_rollout.png) +![Release mode](images/manual_rollout.png) In the previous examples, the Service automatically made changes to the @@ -730,10 +731,6 @@ and the latter is `next`) The new revision will still not receive any traffic, but can be accessed for testing, verification, etc under the `next.my-service...` name. -An admission hook prevents changing `revisions` without also setting -`rolloutPercent`, if `rolloutPercent` is nonzero. This prevents you from -accidentally changing what you're releasing out mid-release. - To put traffic on `ghi`, the user can adjust `rolloutPercent`: ```http @@ -787,9 +784,10 @@ status: status: True ``` -After testing the new revision at `next.my-service.default.mydomain.com`, it can -be promoted to a fully-rolled-out `current` revision by updating the service to -list only `ghi` in the revision list. +After testing and gradually rolling out the new revision at +`next.my-service.default.mydomain.com`, it can be promoted to a fully-rolled-out +`current` revision by updating the service to list only `ghi` in the revision +list. ```http PATCH /apis/serving.knative.dev/v1alpha1/namespaces/default/services/my-service @@ -848,8 +846,53 @@ status: status: True ``` +## 4) Roll back to a known-good Revision + +**_Scenario_**: User realizes that the deployed revision is bad in some way, and +decides to shift traffic as fast as possible to a previous known-good revision. + +``` +$ knative release --service my-service rollback abc +[...] +Rolled back to revision [abc] serving at [my-service.default.mydomain.com] +``` + +**Steps**: + +* Set the service to `release` mode (if it isn't already there), with the + `revisions` list equal to the revision you need to roll back to. Leave the + configuration the same (or copy it over from `runLatest` mode, if the service + wasn't already in `release` mode). + +**Results**: + +* The Route is updated to put 100% of traffic on your rollback Revision. Your + latest ready Revision remains available for validation under the + `latest.my-service.defaultdomain.com`-style name. + +```http +PUT /apis/serving.knative.dev/v1alpha1/namespaces/default/services/my-service +``` +```yaml +apiVersion: serving.knative.dev/v1alpha1 +kind: Service +metadata: + name: my-service +spec: + relase: + revisions: [abc] + configuration: # Copied from spec.runLatest.configuration if needed + revisionTemplate: + spec: + container: + image: gcr.io/... +``` + +Since the Configuration does not change, this does not create a new revision. It +does, however, point all production traffic to the revision named `abc`, +effecting a rollback. -## 4) Deploy a Revision from source +## 5) Deploy a Revision from source **Scenario**: User deploys a revision to an existing service from source rather than a pre-built container @@ -997,7 +1040,7 @@ build fails `LatestReadyRevisionName` will be entirely unset until a Revision is created which can become ready. -## 5) Deploy a Function +## 6) Deploy a Function **Scenario**: User deploys a new function revision to an existing service From d19bf58b87802162ecf228dd465f5a91cb6d2a2d Mon Sep 17 00:00:00 2001 From: Naomi Seyfer Date: Wed, 19 Sep 2018 15:48:14 -0700 Subject: [PATCH 07/11] Add the nonce to the revision --- docs/spec/normative_examples.md | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/docs/spec/normative_examples.md b/docs/spec/normative_examples.md index 3e776eb39f4a..0571243dbc5e 100644 --- a/docs/spec/normative_examples.md +++ b/docs/spec/normative_examples.md @@ -667,6 +667,9 @@ spec: release: configuration: revisionTemplate: + metadata: + labels: + revisionNonce: "l01itSaN0nC3" spec: container: env: # k8s-style strategic merge patch, updating a single list value @@ -677,10 +680,13 @@ spec: As in the previous example, the configuration is updated to trigger the creation of a new revision, and a new revision `ghi` is created that has the same code as -the previous revision `def`, but different config: +the previous revision `def`, but different config. Note that we included a nonce +label in the revision metadata, so that we can easily programatically fetch the +appropriate revision using a label selector to release it later. This nonce is +not required, but is recommended. ```http -GET /apis/serving.knative.dev/v1alpha1/namespaces/default/revisions/ghi +GET /apis/serving.knative.dev/v1alpha1/namespaces/default/revisions?labelSelector=revisionNonce%3Dl01itSaN0nC3 ``` ```yaml From a5025aba914788aada9d1b89085a3ab721009f8f Mon Sep 17 00:00:00 2001 From: Naomi Seyfer Date: Wed, 19 Sep 2018 16:01:15 -0700 Subject: [PATCH 08/11] Respond to review comments --- docs/spec/normative_examples.md | 45 +++++++++++++++++---------------- 1 file changed, 23 insertions(+), 22 deletions(-) diff --git a/docs/spec/normative_examples.md b/docs/spec/normative_examples.md index 0571243dbc5e..eeadaae553bb 100644 --- a/docs/spec/normative_examples.md +++ b/docs/spec/normative_examples.md @@ -588,10 +588,10 @@ current,latest 100% ghi 2018-01-19 12:16 user1 a6f92d1 **Results:** * The system creates the new revision from the configuration, addressable at - `latest.my-service...` (by convention), but traffic is not routed to it until - the rollout to that revision is begun (which markes it as - `next.my-service...`) and the percentage is manually ramped up. Upon - completing the rollout, the next revision is now the current revision. + `latest.my-service...`, but traffic is not routed to it until the rollout to + that revision is begun (which marks it as `next.my-service...`) and the + percentage is manually ramped up. Upon completing the rollout, the next + revision is now the current revision. ![Release mode](images/manual_rollout.png) @@ -601,7 +601,7 @@ configuration (newly created Revision) routable when they became ready. While this pattern is useful for many scenarios such as functions-as-a-service and simple development flows, the Service can also reference Revisions directly in `release` mode to route traffic to two specific revisions: the revision that's -been running, and the new revision the user would like test, or canary a portion +been running, and the new revision the user would like test or canary a portion of traffic to, prior to rolling out entirely. This mode is also useful to roll back to a known-good previous revision. (Note: see [Appendix B](complex_examples.md) for a semi-automatic variation of managed rollouts). @@ -627,9 +627,9 @@ spec: image: gcr.io/... ``` -This causes the Route to be updated to pin traffic the specified -revision (note that the Configuration between the two is equivalent, -and therefore unchanged). +The Service controller updates the Route to put all traffic on the specified +revision (note that the Configuration between the two is equivalent, and +therefore unchanged). ```http PATCH /apis/serving.knative.dev/v1alpha1/namespaces/default/routes/my-service @@ -641,18 +641,19 @@ kind: Route metadata: name: my-service spec: - release: - revisions: [def] - configuration: # Copied from spec.runLatest.configuration - revisionTemplate: - spec: - container: - image: gcr.io/... + rollout: + traffic: + - revisionName: def + name: current # addressable as current.my-service.default.mydomain.com + percent: 100 + - configurationName: my-service # LatestReadyRevision of my-service + name: latest # addressable as latest.my-service.default.mydomain.com + percent: 0 # no direct traffic ever. ``` -Next, the service is updated with the new variables, which causes the -service controller to update the Configuration, in this case updating -the environment but keeping the same container image: +Next, the user updates the Service with the new variables, which causes the +service controller to update the Configuration, in this case updating the +environment but keeping the same container image: ```http PATCH /apis/serving.knative.dev/v1alpha1/namespaces/default/services/my-service @@ -711,9 +712,9 @@ status: ``` Even when ready, the new revision does not automatically start serving -production traffic, as the route was pinned to revision `def`. It will, however, -be optionally accessible under the name `latest.my-service...` for initial -manual testing. +production traffic, as the route is still directing all traffic to revision +`def`. It will, however, be optionally accessible under the name +`latest.my-service...` for initial validation. The user can then begin the rollout of revision ghi: @@ -812,7 +813,7 @@ spec: This causes the service to update the route to assign 100% of traffic to ghi. Once the update has been completed, if the latest ready revision is the same as -the pinned revision, the names `current` and `latest` will point to the same +the current revision, the names `current` and `latest` will point to the same revision. The name `next` is inactive until you're rolling out a revision again. Note that throughout this whole process, `latest` remains pointing to the latest From 050de61517e3f6484ed47fe97a69917eafa8bcaf Mon Sep 17 00:00:00 2001 From: Naomi Seyfer Date: Mon, 24 Sep 2018 15:00:06 -0700 Subject: [PATCH 09/11] Fix typos and grammar --- docs/spec/normative_examples.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/spec/normative_examples.md b/docs/spec/normative_examples.md index eeadaae553bb..a4ad667e603b 100644 --- a/docs/spec/normative_examples.md +++ b/docs/spec/normative_examples.md @@ -618,7 +618,7 @@ kind: Service metadata: name: my-service spec: - relase: + release: revisions: [def] configuration: # Copied from spec.runLatest.configuration revisionTemplate: @@ -716,7 +716,7 @@ production traffic, as the route is still directing all traffic to revision `def`. It will, however, be optionally accessible under the name `latest.my-service...` for initial validation. -The user can then begin the rollout of revision ghi: +The user can then begin the rollout of revision `ghi`: ```http PATCH /apis/serving.knative.dev/v1alpha1/namespaces/default/services/my-service @@ -734,7 +734,7 @@ spec: This makes the route update the `next` name to point to the revision `ghi`. (The list of revisions can contain one or two items. If two, the first is `current` -and the latter is `next`) The new revision will still not receive any traffic, +and the latter is `next`.) The new revision will still not receive any traffic, but can be accessed for testing, verification, etc under the `next.my-service...` name. @@ -855,7 +855,7 @@ status: ## 4) Roll back to a known-good Revision -**_Scenario_**: User realizes that the deployed revision is bad in some way, and +**_Scenario_**: User realizes that the deployed revision is bad in some way and decides to shift traffic as fast as possible to a previous known-good revision. ``` @@ -886,7 +886,7 @@ kind: Service metadata: name: my-service spec: - relase: + release: revisions: [abc] configuration: # Copied from spec.runLatest.configuration if needed revisionTemplate: From 56cb0e9ca2f4bc86dbe7c37733f0fcf5bc54a21d Mon Sep 17 00:00:00 2001 From: Naomi Seyfer Date: Mon, 22 Oct 2018 14:30:22 -0700 Subject: [PATCH 10/11] Respond to comments --- .../images/{manual_rollout.png => release_mode.png} | Bin docs/spec/normative_examples.md | 8 ++++---- 2 files changed, 4 insertions(+), 4 deletions(-) rename docs/spec/images/{manual_rollout.png => release_mode.png} (100%) diff --git a/docs/spec/images/manual_rollout.png b/docs/spec/images/release_mode.png similarity index 100% rename from docs/spec/images/manual_rollout.png rename to docs/spec/images/release_mode.png diff --git a/docs/spec/normative_examples.md b/docs/spec/normative_examples.md index a4ad667e603b..d6e2af2700fd 100644 --- a/docs/spec/normative_examples.md +++ b/docs/spec/normative_examples.md @@ -11,7 +11,7 @@ Examples in this section illustrate: * [Creating a new Service with a pre-built container](#2-creating-a-new-service-with-a-pre-built-container) * [Configuration changes and managed rollout options](#3-managed-release-of-a-new-revision---config-change-only) -* [Roll back to a known-good revision](#4-roll-back-to-a-known-good-revision) +* [Roll back to a known-good revision](#4-roll-back-to-a-known-good-revision) * [Creating a revision from source](#5-deploy-a-revision-from-source) * [Creating a function from source](#6-deploy-a-function) @@ -534,7 +534,7 @@ current,latest 100% def 2018-01-18 20:34 user1 a6f92d1 $ knative deploy --service my-service --env HELLO="blurg" [...] Deployed revision ghi to https://latest.my-service.default.mydomain.com -You can begin rolling out this revision with [knative rollout begin ghi] +You can begin rolling out this revision with [knative release begin ghi] $ knative revisions list --service my-service Route Traffic Id Date Deployer Git SHA @@ -556,7 +556,7 @@ $ knative release percent 5 $ knative revisions list --service my-service Route Traffic Id Date Deployer Git SHA next,latest 5% ghi 2018-01-19 12:16 user1 a6f92d1 -current 100% def 2018-01-18 20:34 user1 a6f92d1 +current 95% def 2018-01-18 20:34 user1 a6f92d1 abc 2018-01-17 10:32 user1 33643fc $ knative release --service my-service percent 50 @@ -593,7 +593,7 @@ current,latest 100% ghi 2018-01-19 12:16 user1 a6f92d1 percentage is manually ramped up. Upon completing the rollout, the next revision is now the current revision. -![Release mode](images/manual_rollout.png) +![Release mode](images/release_mode.png) In the previous examples, the Service automatically made changes to the From 0e9a0d43c12c6d2147397265ef3c542e2d083ae5 Mon Sep 17 00:00:00 2001 From: Naomi Seyfer Date: Tue, 27 Nov 2018 17:46:36 -0800 Subject: [PATCH 11/11] s/next/candidate/ --- docs/spec/normative_examples.md | 46 ++++++++++++++++----------------- 1 file changed, 23 insertions(+), 23 deletions(-) diff --git a/docs/spec/normative_examples.md b/docs/spec/normative_examples.md index d6e2af2700fd..246400c60d1f 100644 --- a/docs/spec/normative_examples.md +++ b/docs/spec/normative_examples.md @@ -545,19 +545,19 @@ current 100% def 2018-01-18 20:34 user1 a6f92d1 $ knative release --service my-service begin ghi $ knative revisions list --service my-service -Route Traffic Id Date Deployer Git SHA -next,latest 0% ghi 2018-01-19 12:16 user1 a6f92d1 -current 100% def 2018-01-18 20:34 user1 a6f92d1 - abc 2018-01-17 10:32 user1 33643fc +Route Traffic Id Date Deployer Git SHA +candidate,latest 0% ghi 2018-01-19 12:16 user1 a6f92d1 +current 100% def 2018-01-18 20:34 user1 a6f92d1 + abc 2018-01-17 10:32 user1 33643fc $ knative release percent 5 [...] $ knative revisions list --service my-service -Route Traffic Id Date Deployer Git SHA -next,latest 5% ghi 2018-01-19 12:16 user1 a6f92d1 -current 95% def 2018-01-18 20:34 user1 a6f92d1 - abc 2018-01-17 10:32 user1 33643fc +Route Traffic Id Date Deployer Git SHA +candidate,latest 5% ghi 2018-01-19 12:16 user1 a6f92d1 +current 95% def 2018-01-18 20:34 user1 a6f92d1 + abc 2018-01-17 10:32 user1 33643fc $ knative release --service my-service percent 50 [...] @@ -565,10 +565,10 @@ $ knative release --service my-service finish [...] $ knative revisions list --service my-service -Route Traffic Id Date Deployer Git SHA -current,latest 100% ghi 2018-01-19 12:16 user1 a6f92d1 - def 2018-01-18 20:34 user1 a6f92d1 - abc 2018-01-17 10:32 user1 33643fc +Route Traffic Id Date Deployer Git SHA +current,latest 100% ghi 2018-01-19 12:16 user1 a6f92d1 + def 2018-01-18 20:34 user1 a6f92d1 + abc 2018-01-17 10:32 user1 33643fc ``` **Steps**: @@ -579,9 +579,9 @@ current,latest 100% ghi 2018-01-19 12:16 user1 a6f92d1 * Update the Service with the new configuration (env var). * Update the Service include the new revision in its revision list, which makes - it address the new Revision as `next`. + it address the new Revision as `candidate`. -* Adjust the `percentRollout` controlling the traffic on `next`. +* Adjust the `percentRollout` controlling the traffic on `candidate`. * Complete the rollout so the new revision is `current`. @@ -589,8 +589,8 @@ current,latest 100% ghi 2018-01-19 12:16 user1 a6f92d1 * The system creates the new revision from the configuration, addressable at `latest.my-service...`, but traffic is not routed to it until the rollout to - that revision is begun (which marks it as `next.my-service...`) and the - percentage is manually ramped up. Upon completing the rollout, the next + that revision is begun (which marks it as `candidate.my-service...`) and the + percentage is manually ramped up. Upon completing the rollout, the candidate revision is now the current revision. ![Release mode](images/release_mode.png) @@ -732,11 +732,11 @@ spec: rolloutPercent: 0 ``` -This makes the route update the `next` name to point to the revision `ghi`. (The +This makes the route update the `candidate` name to point to the revision `ghi`. (The list of revisions can contain one or two items. If two, the first is `current` -and the latter is `next`.) The new revision will still not receive any traffic, +and the latter is `candidate`.) The new revision will still not receive any traffic, but can be accessed for testing, verification, etc under the -`next.my-service...` name. +`candidate.my-service...` name. To put traffic on `ghi`, the user can adjust `rolloutPercent`: @@ -769,7 +769,7 @@ spec: name: current # addressable as current.my-service.default.mydomain.com percent: 95 - revisionName: ghi - name: next # addressable as next.my-service.default.mydomain.com + name: candidate # addressable as candidate.my-service.default.mydomain.com percent: 5 - configurationName: my-service # LatestReadyRevision of my-service name: latest # addressable as latest.my-service.default.mydomain.com @@ -781,7 +781,7 @@ status: name: current # addressable as current.my-service.default.mydomain.com percent: 95 - revisionName: ghi - name: next # addressable as next.my-service.default.mydomain.com + name: candidate # addressable as candidate.my-service.default.mydomain.com percent: 5 - configurationName: my-service # LatestReadyRevision of my-service name: latest @@ -792,7 +792,7 @@ status: ``` After testing and gradually rolling out the new revision at -`next.my-service.default.mydomain.com`, it can be promoted to a fully-rolled-out +`candidate.my-service.default.mydomain.com`, it can be promoted to a fully-rolled-out `current` revision by updating the service to list only `ghi` in the revision list. @@ -814,7 +814,7 @@ This causes the service to update the route to assign 100% of traffic to ghi. Once the update has been completed, if the latest ready revision is the same as the current revision, the names `current` and `latest` will point to the same -revision. The name `next` is inactive until you're rolling out a revision again. +revision. The name `candidate` is inactive until you're rolling out a revision again. Note that throughout this whole process, `latest` remains pointing to the latest ready revision of the service. This allows your team to continue to pre-check