From 6a178a450fd0304bc9b0858abe2ac76d9c7ebfee Mon Sep 17 00:00:00 2001 From: Adam Miller <1402860+adammil2000@users.noreply.github.com> Date: Tue, 5 May 2020 11:37:37 -0700 Subject: [PATCH] Add docs for Wait for Resource Status to Apply Configuration (#7157) * Reset branch and fix bad merge * Update content/en/docs/reference/config/config-status/index.md Co-authored-by: Mitch Connors * Update content/en/docs/reference/config/config-status/index.md Co-authored-by: Mitch Connors * Another linter fix * Recover dropped text * Reapply lost changes made via the GitHub UI * PR comment Co-authored-by: Mitch Connors --- .../mesh/config-resource-ready/index.md | 54 +++++++++ .../reference/config/config-status/index.md | 112 ++++++++++++++++++ 2 files changed, 166 insertions(+) create mode 100644 content/en/docs/ops/configuration/mesh/config-resource-ready/index.md create mode 100644 content/en/docs/reference/config/config-status/index.md diff --git a/content/en/docs/ops/configuration/mesh/config-resource-ready/index.md b/content/en/docs/ops/configuration/mesh/config-resource-ready/index.md new file mode 100644 index 0000000000..e75c2e0f93 --- /dev/null +++ b/content/en/docs/ops/configuration/mesh/config-resource-ready/index.md @@ -0,0 +1,54 @@ +--- +title: Wait for Resource Status to Apply Configuration +description: Describes how to wait to apply mesh configuration until a resource reaches a given status or readiness. +weight: 15 +--- + +{{< warning >}} +This feature is in the Alpha stage, see +[Istio Feature Status](/about/feature-stages/). Your feedback is welcome in the +[Istio User Experience discussion](https://discuss.istio.io/c/UX/23). Currently, +this feature is tested only for single, low volume clusters with a single +control plane revision. +{{< /warning >}} + +Istio's mesh configuration is declarative, which means that you define a +configuration and Istio propagates the changes through the mesh over time. As a +result, your command might attempt to use your service mesh before +the relevant resources are ready. + +In Istio 1.6 and later, you can use the `kubectl wait` command to have more +control over the way that Istio applies configuration changes to the mesh. To +make this possible, the `kubectl wait` command monitors the +[`status` field](/docs/reference/config/config-status/) of the resource's +status, which Istio updates as it propagates configuration changes. + +## Before you begin + +This feature is off by default. Enable the `status` field as part of Istio +installation using the following command. If you enable it after installation, +you must re-deploy the control plane. + +{{< text bash >}} +$ istioctl manifest apply --set values.pilot.env.PILOT_ENABLE_STATUS=true --set values.global.istiod.enableAnalysis=true +{{< /text >}} + +## Wait for resource readiness + +You can apply a change to a virtual service and then wait for completion, using +the following commands: + +{{< text bash >}} +$ kubectl apply -f virtual_service_name.yaml +$ kubectl wait --for=condition=Reconciled virtual_service/name +{{< /text >}} + +This blocking command does not release until the virtual service has been +distributed to all proxies in the mesh, or until the command times out. + +When you use the `kubectl wait` command in a script, the return code +will be `0` for success, or a non-zero value for time out. + +For more information about usage and syntax, see the +[kubectl wait](https://kubernetes.io/docs/reference/generated/kubectl/kubectl-commands#wait) +command. diff --git a/content/en/docs/reference/config/config-status/index.md b/content/en/docs/reference/config/config-status/index.md new file mode 100644 index 0000000000..b6a3e881fc --- /dev/null +++ b/content/en/docs/reference/config/config-status/index.md @@ -0,0 +1,112 @@ +--- +title: Configuration Status Field +description: Describes the role of the `status` field in configuration workflow. +weight: 21 +--- + +{{< warning >}} +This feature is in the Alpha stage, see +[Istio Feature Status](/about/feature-stages/). Your feedback is welcome in the +[Istio User Experience discussion](https://discuss.istio.io/c/UX/23). Currently, +this feature is tested only for single, low volume clusters with a single +control plane revision. +{{< /warning >}} + +Istio 1.6 and later provides information about the propagation of configuration +changes through the mesh, using the `status` field of the resource. +Status is disabled by default, and can be enabled during install with: + +{{< text bash >}} +$ istioctl manifest apply --set values.pilot.env.PILOT_ENABLE_STATUS=true --set values.global.istiod.enableAnalysis=true +{{< /text >}} + +The `status` field contains the state of a resource's configuration with various +informational messages, including: + +* The resource's readiness. +* How many data plane instances are associated with it. +* Information for the output of tools, such as `istioctl analyze`. + +For example, the `kubectl wait` command monitors the `status` field to determine +whether to unblock configuration and resume. For more information, see +[Wait for Resource Status to Apply Configuration](/docs/ops/configuration/mesh/config-resource-ready/). + +## View the `status` field + +You can view the contents of the `status` field of a resource using +`kubectl get`. For example, to view the status of a virtual service, use the following +command: + +{{< text bash >}} +$ kubectl get virtualservice -o yaml +{{< /text >}} + +In the output, the `status` field contains several nested fields with details +about the process of propagating configuration changes through the mesh. + +{{< text yaml >}} +status: + conditions: + - lastProbeTime: null + lastTransitionTime: "2019-12-26T22:06:34Z" + message: "61/122 complete" + reason: "stillPropagating" + status: "False" + type: Reconciled + - lastProbeTime: null + lastTransitionTime: "2019-12-26T22:06:56Z" + message: "1 Error and 1 Warning found. See validationMessages field for details" + reason: "errorsFound" + status: "False" + type: PassedAnalysis + validationMessages: + - code: IST0101 + level: Error + message: 'Referenced gateway not found: "bogus-gateway"' + - code: IST0102 + level: Warn + message: 'mTLS not enabled for virtual service' +{{< /text >}} + +## The `conditions` field + +Conditions represent possible states of the resource. The `type` field of a +condition can have the following values: + +* `PassedAnalysis` +* `Reconciled` + +When you apply a configuration, a condition of each of these types is added to the +`conditions` field. + +The `status` field of the `Reconciled` type condition is initialized to `False` +to indicate the resource is still in the process of being distributed to all the proxies. +When finished reconciling, the status will become `True`. The `status` field might +transition to `True` instantaneously, depending on the speed of the cluster. + +The `status` field of the `PassedAnalysis` type condition will have a value of +`True` or `False` depending on whether or not Istio's background analyzers have +detected a problem with your config. If `False`, the problem(s) will be detailed in the +`validationMessages` field. + +The `PassedAnalysis` condition is an informational field only. It does not +block the application of an invalid configuration. It is possible for the status to +indicate that validation failed, but applying the configuration was successful. +This means Istio was able to set the new configuration, but the configuration was +invalid, likely due to a syntax error or similar problem. + +## The `validationMessages` field + +In case of a validation failure, check the `validationMessages` field for +more information. The `validationMessages` field has details about the validation +process, such as error messages indicating that Istio cannot apply the +configuration, and warning or informational messages that did not result in an +error. + +If the condition of type `PassedValidation` has a status of `False`, there will +be `validationMessages` explaining the problem. There might be messages present +when `PassedValidation` status is `True`, because those are informational +messages. + +For validation message examples, see +[Configuration Analysis Messages](/docs/reference/config/analysis/).