From 08189f25ef961ef00d3d4ed7a784c0d6e1de928b Mon Sep 17 00:00:00 2001 From: Martin Taillefer Date: Tue, 5 Nov 2019 12:03:41 -0800 Subject: [PATCH] Update reference docs. (#5392) --- Makefile.core.mk | 2 +- .../reference/commands/istioctl/index.html | 100 ++++++++++++++++-- .../authorization-policy/index.html | 2 +- .../istio.rbac.v1alpha1/index.html | 5 +- data/analysis.yaml | 20 +--- examples/examples__bookinfo.snippets.txt | 39 +++++++ ...curity__mututal_tls_migration.snippets.txt | 78 ++++++++++++++ ...traffic_management__mirroring.snippets.txt | 44 ++++---- scripts/grab_examples.sh | 3 + static/operator.yaml | 6 +- 10 files changed, 244 insertions(+), 55 deletions(-) rename content/en/docs/reference/config/{security/v1beta1 => authorization}/authorization-policy/index.html (99%) create mode 100644 examples/examples__bookinfo.snippets.txt create mode 100644 examples/tasks__security__mututal_tls_migration.snippets.txt diff --git a/Makefile.core.mk b/Makefile.core.mk index f7e88a0311..db8f1d8c17 100644 --- a/Makefile.core.mk +++ b/Makefile.core.mk @@ -63,7 +63,7 @@ update_operator_yamls: update_examples: @scripts/grab_examples.sh $(SOURCE_BRANCH_NAME) -update_all: update_ref_docs update_operator_yaml update_examples +update_all: update_ref_docs update_operator_yamls update_examples include common/Makefile.common.mk diff --git a/content/en/docs/reference/commands/istioctl/index.html b/content/en/docs/reference/commands/istioctl/index.html index fd6893a789..f204eed5d2 100644 --- a/content/en/docs/reference/commands/istioctl/index.html +++ b/content/en/docs/reference/commands/istioctl/index.html @@ -930,6 +930,7 @@ istioctl experimental analyze -k -d false

istioctl experimental auth

Commands to inspect and interact with the authentication (TLS, JWT) and authorization (RBAC) policies in the mesh check - check the TLS/JWT/RBAC settings based on the Envoy config + convert - convert v1alpha1 RBAC policies to v1beta1 authorization policies validate - check for potential incorrect usage in authorization policy files.

@@ -971,6 +972,10 @@ istioctl experimental analyze -k -d false

Examples

  # Check the TLS/JWT/RBAC settings for pod httpbin-88ddbcfdd-nt5jb:
   istioctl experimental auth check httpbin-88ddbcfdd-nt5jb
+
+  # Convert the v1alpha1 RBAC policies currently applied in the cluster to v1beta1 authorization policies:
+  istioctl experimental auth convert > v1beta1-authz.yaml
+

istioctl experimental auth check

Check analyzes the TLS/JWT/RBAC settings directly based on the Envoy config. The Envoy config could @@ -1041,6 +1046,88 @@ the cluster results of the client pod and the listener results of the server pod # Check the TLS/JWT/RBAC policy status from a config dump file: istioctl experimental auth check -f httpbin_config_dump.txt +

istioctl experimental auth convert

+

Convert converts Istio v1alpha1 RBAC policy to v1beta1 authorization policy. The command talks to Kubernetes +API server to get all the information needed to complete the conversion, including the currently applied v1alpha1 +RBAC policies, the Istio config-map for root namespace configuration and the k8s Service translating the +service name to workload selector.

+

The tool can also be used in offline mode without talking to the Kubernetes API server. In this mode, +all needed information is provided through the command line.

+

Note: The converter tool makes a best effort attempt to keep the syntax unchanged when +converting v1alph1 RBAC policy to v1beta1 policy. However, in some cases, strict +mapping with equivalent syntax is not possible (e.g., constraints no longer valid +in the new workload oriented model, converting a service name containing a wildcard +to workload selector).

+

Please always review the converted policies before applying them.

+

THIS COMMAND IS STILL UNDER ACTIVE DEVELOPMENT AND NOT READY FOR PRODUCTION USE. +

+
istioctl experimental auth convert [flags]
+
+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FlagsShorthandDescription
--context <string>The name of the kubeconfig context to use (default ``)
--file <stringSlice>-fv1alpha1 RBAC policy that needs to be converted to v1beta1 authorization policy (default `[]`)
--istioNamespace <string>-iIstio system namespace (default `istio-system`)
--kubeconfig <string>-cKubernetes configuration file (default ``)
--log_output_level <string>Comma-separated minimum per-scope logging level of messages to output, in the form of <scope>:<level>,<scope>:<level>,... where scope can be one of [ads, all, analysis, attributes, authn, cacheLog, citadelClientLog, configMapController, conversions, default, googleCAClientLog, grpcAdapter, kube, kube-converter, mcp, meshconfig, model, name, patch, processing, rbac, resource, runtime, sdsServiceLog, secretFetcherLog, source, stsClientLog, tpath, translator, util, validation, vaultClientLog] and level can be one of [debug, info, warn, error, fatal, none] (default `default:info,validation:error,processing:error,source:error,analysis:warn`)
--meshConfigFile <string>-mIstio MeshConfig file that provides the root namespace value (default ``)
--meshConfigMapName <string>ConfigMap name for Istio mesh configuration (default `istio`)
--namespace <string>-nConfig namespace (default ``)
--service <stringSlice>-sKubernetes Service resource that provides the mapping between service and workload (default `[]`)
+

Examples

+
  # Convert the v1alpha1 RBAC policy currently applied in the cluster:
+  istioctl experimental auth convert > v1beta1-authz.yaml
+
+  # Convert the v1alpha1 RBAC policy provided through command line: 
+  istioctl experimental auth convert -f v1alpha1-policy-1.yaml,v1alpha1-policy-2.yaml
+  --service services.yaml --meshConfigFile meshConfig.yaml > v1beta1-authz.yaml
+
+

istioctl experimental auth validate

This command goes through all authorization policy files and finds potential issues such as: * ServiceRoleBinding refers to a non existing ServiceRole. @@ -1189,7 +1276,7 @@ the cluster results of the client pod and the listener results of the server pod --service-account <string> -create a secret with this service account's credentials. (default `istio-pilot`) +create a secret with this service account's credentials. (default `istio-pilot-service-account`) @@ -2165,7 +2252,7 @@ THIS COMMAND IS STILL UNDER ACTIVE DEVELOPMENT AND NOT READY FOR PRODUCTION USE. 

istioctl experimental remove-from-mesh service productpage

istioctl experimental upgrade

-

The mesh upgrade command checks for upgrade version eligibility and, if eligible, upgrades the Istio control plane components in-place. Warning: traffic may be disrupted during upgrade. Please ensure PodDisruptionBudgets are defined to maintain service continuity.

+

The upgrade command checks for upgrade version eligibility and, if eligible, upgrades the Istio control plane components in-place. Warning: traffic may be disrupted during upgrade. Please ensure PodDisruptionBudgets are defined to maintain service continuity.

istioctl experimental upgrade [flags]
@@ -2223,9 +2310,9 @@ THIS COMMAND IS STILL UNDER ACTIVE DEVELOPMENT AND NOT READY FOR PRODUCTION USE. - - - + + + @@ -2244,9 +2331,6 @@ THIS COMMAND IS STILL UNDER ACTIVE DEVELOPMENT AND NOT READY FOR PRODUCTION USE.
Config namespace (default ``)
--skipConfirmation-yIf skipConfirmation is set, skips the prompting confirmation for value changes in this upgrade --skip-confirmationIf skip-confirmation is set, skips the prompting confirmation for value changes in this upgrade
--verbose
-

Examples

-
mesh upgrade
-

istioctl experimental wait

Waits for the specified condition to be true of an Istio resource. For example:

istioctl experimental wait --for=distribution virtual-service bookinfo.default

diff --git a/content/en/docs/reference/config/security/v1beta1/authorization-policy/index.html b/content/en/docs/reference/config/authorization/authorization-policy/index.html similarity index 99% rename from content/en/docs/reference/config/security/v1beta1/authorization-policy/index.html rename to content/en/docs/reference/config/authorization/authorization-policy/index.html index cede4542e0..37af34a71f 100644 --- a/content/en/docs/reference/config/security/v1beta1/authorization-policy/index.html +++ b/content/en/docs/reference/config/authorization/authorization-policy/index.html @@ -3,7 +3,7 @@ WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. PLEASE MODIFY THE ORIGINAL source_repo: https://github.com/istio/api title: Authorization Policy description: Configuration for access control on workloads. -location: https://istio.io/docs/reference/config/security/v1beta1/authorization-policy.html +location: https://istio.io/docs/reference/config/authorization/authorization-policy.html layout: protoc-gen-docs generator: protoc-gen-docs number_of_entries: 8 diff --git a/content/en/docs/reference/config/authorization/istio.rbac.v1alpha1/index.html b/content/en/docs/reference/config/authorization/istio.rbac.v1alpha1/index.html index f94041028b..09c40b5330 100644 --- a/content/en/docs/reference/config/authorization/istio.rbac.v1alpha1/index.html +++ b/content/en/docs/reference/config/authorization/istio.rbac.v1alpha1/index.html @@ -1,13 +1,16 @@ --- WARNING: THIS IS AN AUTO-GENERATED FILE, DO NOT EDIT. PLEASE MODIFY THE ORIGINAL SOURCE IN THE 'https://github.com/istio/api' REPO source_repo: https://github.com/istio/api -title: RBAC +title: RBAC (deprecated) description: Configuration for Role Based Access Control. location: https://istio.io/docs/reference/config/authorization/istio.rbac.v1alpha1.html layout: protoc-gen-docs generator: protoc-gen-docs number_of_entries: 9 --- +

Note: The v1alpha1 RBAC policy is deprecated by the v1beta1 Authorization policy. +This page is kept for migration purpose and will be removed in Istio 1.6.

+

Istio RBAC (Role Based Access Control) defines ServiceRole and ServiceRoleBinding objects.

diff --git a/data/analysis.yaml b/data/analysis.yaml index 179538a931..e7038d2a62 100644 --- a/data/analysis.yaml +++ b/data/analysis.yaml @@ -10,26 +10,8 @@ messages: - name: detail type: string - - name: "NotYetImplemented" - code: IST0002 - level: Error - description: "A feature that the configuration is depending on is not implemented yet." - template: "Not yet implemented: %s" - args: - - name: detail - type: string - - - name: "ParseError" - code: IST0003 - level: Warning - description: "There was a parse error during the parsing of the configuration text" - template: "Parse error: %s" - args: - - name: detail - type: string - - name: "Deprecated" - code: IST0004 + code: IST0002 level: Warning description: "A feature that the configuration is depending on is now deprecated." template: "Deprecated: %s" diff --git a/examples/examples__bookinfo.snippets.txt b/examples/examples__bookinfo.snippets.txt new file mode 100644 index 0000000000..c9ad258fd4 --- /dev/null +++ b/examples/examples__bookinfo.snippets.txt @@ -0,0 +1,39 @@ +# Created by TestBookinfo. DO NOT EDIT THIS FILE MANUALLY! + +$snippet automatic_sidecar_injection.sh syntax="bash" +$ kubectl label namespace default istio-injection=enabled +$endsnippet + +$snippet deploy_bookinfo_application.sh syntax="bash" +$ kubectl apply -f @samples/bookinfo/platform/kube/bookinfo.yaml@ +$endsnippet + +$snippet verify_service.sh syntax="bash" +$ kubectl get services +$endsnippet + +$snippet verify_service.sh_output.txt syntax="text" +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +details ClusterIP 10.101.120.116 9080/TCP 1s +kubernetes ClusterIP 10.96.0.1 443/TCP 8m48s +productpage ClusterIP 10.109.229.155 9080/TCP 0s +ratings ClusterIP 10.105.61.20 9080/TCP 1s +reviews ClusterIP 10.104.30.214 9080/TCP 0s + +$endsnippet + +$snippet verify_pods.sh syntax="bash" +$ kubectl get pods +$endsnippet + +$snippet verify_pods.sh_output.txt syntax="text" +NAME READY STATUS RESTARTS AGE +details-v1-74f858558f-sp2zc 2/2 Running 0 39s +productpage-v1-76589d9fdc-krrxc 2/2 Running 0 38s +ratings-v1-7855f5bcb9-c6vjp 2/2 Running 0 39s +reviews-v1-64bc5454b9-qsfww 2/2 Running 0 39s +reviews-v2-76c64d4bdf-95h6m 2/2 Running 0 39s +reviews-v3-5545c7c78f-9ptfw 2/2 Running 0 39s + +$endsnippet + diff --git a/examples/tasks__security__mututal_tls_migration.snippets.txt b/examples/tasks__security__mututal_tls_migration.snippets.txt new file mode 100644 index 0000000000..26a6bf325f --- /dev/null +++ b/examples/tasks__security__mututal_tls_migration.snippets.txt @@ -0,0 +1,78 @@ +# Created by TestMutualTLSMigration. DO NOT EDIT THIS FILE MANUALLY! + +$snippet create_ns_foo_bar_legacy.sh syntax="bash" +$ kubectl create ns foo +$ kubectl apply -f <(istioctl kube-inject -f @samples/httpbin/httpbin.yaml@) -n foo +$ kubectl apply -f <(istioctl kube-inject -f @samples/sleep/sleep.yaml@) -n foo +$ kubectl create ns bar +$ kubectl apply -f <(istioctl kube-inject -f @samples/httpbin/httpbin.yaml@) -n bar +$ kubectl apply -f <(istioctl kube-inject -f @samples/sleep/sleep.yaml@) -n bar +$ kubectl create ns legacy +$ kubectl apply -f samples/sleep/sleep.yaml -n legacy +$endsnippet + +$snippet curl_foo_bar_legacy.sh syntax="bash" outputis="text" +$ for from in "foo" "bar" "legacy"; do kubectl exec $(kubectl get pod -l app=sleep -n ${from} -o jsonpath={.items..metadata.name}) -c sleep -n ${from} -- curl http://httpbin.foo:8000/ip -s -o /dev/null -w "sleep.${from} to httpbin.foo: %{http_code}\n"; done +sleep.foo to httpbin.foo: 200 +sleep.bar to httpbin.foo: 200 +sleep.legacy to httpbin.foo: 200 +$endsnippet + +$snippet verify_initial_policies.sh syntax="bash" outputis="text" +$ kubectl get policies.authentication.istio.io --all-namespaces +NAMESPACE NAME AGE +istio-system grafana-ports-mtls-disabled 3m22s +$endsnippet + +$snippet configure_mtls_destinationrule.sh syntax="bash" +$ cat <