Update reference docs. (#5392)

This commit is contained in:
Martin Taillefer 2019-11-05 12:03:41 -08:00 committed by GitHub
parent 905dc2fe90
commit 08189f25ef
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 244 additions and 55 deletions

View File

@ -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

View File

@ -930,6 +930,7 @@ istioctl experimental analyze -k -d false
<h2 id="istioctl-experimental-auth">istioctl experimental auth</h2>
<p>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.
</p>
<table class="command-flags">
@ -971,6 +972,10 @@ istioctl experimental analyze -k -d false
<h3 id="istioctl-experimental-auth Examples">Examples</h3>
<pre class="language-bash"><code> # 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 &gt; v1beta1-authz.yaml
</code></pre>
<h2 id="istioctl-experimental-auth-check">istioctl experimental auth check</h2>
<p>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
</code></pre>
<h2 id="istioctl-experimental-auth-convert">istioctl experimental auth convert</h2>
<p>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.</p>
<p>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.</p>
<p>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).</p>
<p>Please always review the converted policies before applying them.</p>
<p>THIS COMMAND IS STILL UNDER ACTIVE DEVELOPMENT AND NOT READY FOR PRODUCTION USE.
</p>
<pre class="language-bash"><code>istioctl experimental auth convert [flags]
</code></pre>
<table class="command-flags">
<thead>
<tr>
<th>Flags</th>
<th>Shorthand</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>--context &lt;string&gt;</code></td>
<td></td>
<td>The name of the kubeconfig context to use (default ``)</td>
</tr>
<tr>
<td><code>--file &lt;stringSlice&gt;</code></td>
<td><code>-f</code></td>
<td>v1alpha1 RBAC policy that needs to be converted to v1beta1 authorization policy (default `[]`)</td>
</tr>
<tr>
<td><code>--istioNamespace &lt;string&gt;</code></td>
<td><code>-i</code></td>
<td>Istio system namespace (default `istio-system`)</td>
</tr>
<tr>
<td><code>--kubeconfig &lt;string&gt;</code></td>
<td><code>-c</code></td>
<td>Kubernetes configuration file (default ``)</td>
</tr>
<tr>
<td><code>--log_output_level &lt;string&gt;</code></td>
<td></td>
<td>Comma-separated minimum per-scope logging level of messages to output, in the form of &lt;scope&gt;:&lt;level&gt;,&lt;scope&gt;:&lt;level&gt;,... 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`)</td>
</tr>
<tr>
<td><code>--meshConfigFile &lt;string&gt;</code></td>
<td><code>-m</code></td>
<td>Istio MeshConfig file that provides the root namespace value (default ``)</td>
</tr>
<tr>
<td><code>--meshConfigMapName &lt;string&gt;</code></td>
<td></td>
<td>ConfigMap name for Istio mesh configuration (default `istio`)</td>
</tr>
<tr>
<td><code>--namespace &lt;string&gt;</code></td>
<td><code>-n</code></td>
<td>Config namespace (default ``)</td>
</tr>
<tr>
<td><code>--service &lt;stringSlice&gt;</code></td>
<td><code>-s</code></td>
<td>Kubernetes Service resource that provides the mapping between service and workload (default `[]`)</td>
</tr>
</tbody>
</table>
<h3 id="istioctl-experimental-auth-convert Examples">Examples</h3>
<pre class="language-bash"><code> # Convert the v1alpha1 RBAC policy currently applied in the cluster:
istioctl experimental auth convert &gt; 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 &gt; v1beta1-authz.yaml
</code></pre>
<h2 id="istioctl-experimental-auth-validate">istioctl experimental auth validate</h2>
<p>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
<tr>
<td><code>--service-account &lt;string&gt;</code></td>
<td></td>
<td>create a secret with this service account&#39;s credentials. (default `istio-pilot`)</td>
<td>create a secret with this service account&#39;s credentials. (default `istio-pilot-service-account`)</td>
</tr>
</tbody>
</table>
@ -2165,7 +2252,7 @@ THIS COMMAND IS STILL UNDER ACTIVE DEVELOPMENT AND NOT READY FOR PRODUCTION USE.
<pre class="language-bash"><code>istioctl experimental remove-from-mesh service productpage
</code></pre>
<h2 id="istioctl-experimental-upgrade">istioctl experimental upgrade</h2>
<p>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.</p>
<p>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.</p>
<pre class="language-bash"><code>istioctl experimental upgrade [flags]
</code></pre>
<table class="command-flags">
@ -2223,9 +2310,9 @@ THIS COMMAND IS STILL UNDER ACTIVE DEVELOPMENT AND NOT READY FOR PRODUCTION USE.
<td>Config namespace (default ``)</td>
</tr>
<tr>
<td><code>--skipConfirmation</code></td>
<td><code>-y</code></td>
<td>If skipConfirmation is set, skips the prompting confirmation for value changes in this upgrade </td>
<td><code>--skip-confirmation</code></td>
<td></td>
<td>If skip-confirmation is set, skips the prompting confirmation for value changes in this upgrade </td>
</tr>
<tr>
<td><code>--verbose</code></td>
@ -2244,9 +2331,6 @@ THIS COMMAND IS STILL UNDER ACTIVE DEVELOPMENT AND NOT READY FOR PRODUCTION USE.
</tr>
</tbody>
</table>
<h3 id="istioctl-experimental-upgrade Examples">Examples</h3>
<pre class="language-bash"><code>mesh upgrade
</code></pre>
<h2 id="istioctl-experimental-wait">istioctl experimental wait</h2>
<p>Waits for the specified condition to be true of an Istio resource. For example:</p>
<p>istioctl experimental wait --for=distribution virtual-service bookinfo.default</p>

View File

@ -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

View File

@ -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
---
<p>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.</p>
<p>Istio RBAC (Role Based Access Control) defines ServiceRole and ServiceRoleBinding
objects.</p>

View File

@ -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"

View File

@ -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 <none> 9080/TCP 1s
kubernetes ClusterIP 10.96.0.1 <none> 443/TCP 8m48s
productpage ClusterIP 10.109.229.155 <none> 9080/TCP 0s
ratings ClusterIP 10.105.61.20 <none> 9080/TCP 1s
reviews ClusterIP 10.104.30.214 <none> 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

View File

@ -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 <<EOF | kubectl apply -n foo -f -
apiVersion: "networking.istio.io/v1alpha3"
kind: "DestinationRule"
metadata:
name: "example-httpbin-istio-client-mtls"
spec:
host: httpbin.foo.svc.cluster.local
trafficPolicy:
tls:
mode: ISTIO_MUTUAL
EOF
$endsnippet
$snippet curl_foo_bar_legacy_post_dr.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 httpbin_foo_mtls_only.sh syntax="bash"
$ cat <<EOF | kubectl apply -n foo -f -
apiVersion: "authentication.istio.io/v1alpha1"
kind: "Policy"
metadata:
name: "example-httpbin-strict"
namespace: foo
spec:
targets:
- name: httpbin
peers:
- mtls:
mode: STRICT
EOF
$endsnippet
$snippet curl_foo_bar_legacy_httpbin_foo_mtls.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: 000
command terminated with exit code 56
$endsnippet
$snippet cleanup.sh syntax="bash" outputis="text"
$ kubectl delete ns foo bar legacy
namespace "foo" deleted
namespace "bar" deleted
namespace "legacy" deleted
$endsnippet

View File

@ -132,26 +132,26 @@ $endsnippet
$snippet generate_traffic_1.sh syntax="bash"
$ export SLEEP_POD=$(kubectl -n istio-io-mirror get pod -l app=sleep -o jsonpath={.items..metadata.name})
$ kubectl -n istio-io-mirror exec ${SLEEP_POD} -c sleep -- curl -o /dev/null -s -w "%%{http_code}\n" http://httpbin:8000/ISTIO_IO_MIRROR_TEST_1
$ kubectl -n istio-io-mirror exec ${SLEEP_POD} -c sleep -- curl -o /dev/null -s -w "%{http_code}\n" http://httpbin:8000/ISTIO_IO_MIRROR_TEST_1
$endsnippet
$snippet check_logs_v1_1.sh syntax="bash" outputis="text"
$ export V1_POD=$(kubectl -n istio-io-mirror get pod -l app=httpbin,version=v1 -o jsonpath={.items..metadata.name})
$ kubectl -n istio-io-mirror logs ${V1_POD} -c httpbin
[2019-10-28 19:49:55 +0000] [1] [INFO] Starting gunicorn 19.9.0
[2019-10-28 19:49:55 +0000] [1] [INFO] Listening at: http://0.0.0.0:80 (1)
[2019-10-28 19:49:55 +0000] [1] [INFO] Using worker: sync
[2019-10-28 19:49:55 +0000] [8] [INFO] Booting worker with pid: 8
127.0.0.1 - - [28/Oct/2019:19:50:16 +0000] "GET /ISTIO_IO_MIRROR_TEST_1 HTTP/1.1" 404 233 "-" "curl/7.35.0"
[2019-11-05 18:48:27 +0000] [1] [INFO] Starting gunicorn 19.9.0
[2019-11-05 18:48:27 +0000] [1] [INFO] Listening at: http://0.0.0.0:80 (1)
[2019-11-05 18:48:27 +0000] [1] [INFO] Using worker: sync
[2019-11-05 18:48:27 +0000] [8] [INFO] Booting worker with pid: 8
127.0.0.1 - - [05/Nov/2019:18:48:45 +0000] "GET /ISTIO_IO_MIRROR_TEST_1 HTTP/1.1" 404 233 "-" "curl/7.35.0"
$endsnippet
$snippet check_logs_v2_1.sh syntax="bash" outputis="text"
$ export V2_POD=$(kubectl -n istio-io-mirror get pod -l app=httpbin,version=v2 -o jsonpath={.items..metadata.name})
$ kubectl -n istio-io-mirror logs ${V2_POD} -c httpbin
[2019-10-28 19:49:54 +0000] [1] [INFO] Starting gunicorn 19.9.0
[2019-10-28 19:49:54 +0000] [1] [INFO] Listening at: http://0.0.0.0:80 (1)
[2019-10-28 19:49:54 +0000] [1] [INFO] Using worker: sync
[2019-10-28 19:49:54 +0000] [10] [INFO] Booting worker with pid: 10
[2019-11-05 18:48:28 +0000] [1] [INFO] Starting gunicorn 19.9.0
[2019-11-05 18:48:28 +0000] [1] [INFO] Listening at: http://0.0.0.0:80 (1)
[2019-11-05 18:48:28 +0000] [1] [INFO] Using worker: sync
[2019-11-05 18:48:28 +0000] [9] [INFO] Booting worker with pid: 9
$endsnippet
$snippet mirror_vs.sh syntax="bash"
@ -178,28 +178,28 @@ $endsnippet
$snippet generate_traffic_2.sh syntax="bash"
$ export SLEEP_POD=$(kubectl -n istio-io-mirror get pod -l app=sleep -o jsonpath={.items..metadata.name})
$ kubectl -n istio-io-mirror exec ${SLEEP_POD} -c sleep -- curl -o /dev/null -s -w "%%{http_code}\n" http://httpbin:8000/ISTIO_IO_MIRROR_TEST_2
$ kubectl -n istio-io-mirror exec ${SLEEP_POD} -c sleep -- curl --retry 3 -o /dev/null -s -w "%{http_code}\n" http://httpbin:8000/ISTIO_IO_MIRROR_TEST_2
$endsnippet
$snippet check_logs_v1_2.sh syntax="bash" outputis="text"
$ export V1_POD=$(kubectl -n istio-io-mirror get pod -l app=httpbin,version=v1 -o jsonpath={.items..metadata.name})
$ kubectl -n istio-io-mirror logs ${V1_POD} -c httpbin
[2019-10-28 19:49:55 +0000] [1] [INFO] Starting gunicorn 19.9.0
[2019-10-28 19:49:55 +0000] [1] [INFO] Listening at: http://0.0.0.0:80 (1)
[2019-10-28 19:49:55 +0000] [1] [INFO] Using worker: sync
[2019-10-28 19:49:55 +0000] [8] [INFO] Booting worker with pid: 8
127.0.0.1 - - [28/Oct/2019:19:50:16 +0000] "GET /ISTIO_IO_MIRROR_TEST_1 HTTP/1.1" 404 233 "-" "curl/7.35.0"
127.0.0.1 - - [28/Oct/2019:19:50:27 +0000] "GET /ISTIO_IO_MIRROR_TEST_2 HTTP/1.1" 404 233 "-" "curl/7.35.0"
[2019-11-05 18:48:27 +0000] [1] [INFO] Starting gunicorn 19.9.0
[2019-11-05 18:48:27 +0000] [1] [INFO] Listening at: http://0.0.0.0:80 (1)
[2019-11-05 18:48:27 +0000] [1] [INFO] Using worker: sync
[2019-11-05 18:48:27 +0000] [8] [INFO] Booting worker with pid: 8
127.0.0.1 - - [05/Nov/2019:18:48:45 +0000] "GET /ISTIO_IO_MIRROR_TEST_1 HTTP/1.1" 404 233 "-" "curl/7.35.0"
127.0.0.1 - - [05/Nov/2019:18:48:56 +0000] "GET /ISTIO_IO_MIRROR_TEST_2 HTTP/1.1" 404 233 "-" "curl/7.35.0"
$endsnippet
$snippet check_logs_v2_2.sh syntax="bash" outputis="text"
$ export V2_POD=$(kubectl -n istio-io-mirror get pod -l app=httpbin,version=v2 -o jsonpath={.items..metadata.name})
$ kubectl -n istio-io-mirror logs ${V2_POD} -c httpbin
[2019-10-28 19:49:54 +0000] [1] [INFO] Starting gunicorn 19.9.0
[2019-10-28 19:49:54 +0000] [1] [INFO] Listening at: http://0.0.0.0:80 (1)
[2019-10-28 19:49:54 +0000] [1] [INFO] Using worker: sync
[2019-10-28 19:49:54 +0000] [10] [INFO] Booting worker with pid: 10
127.0.0.1 - - [28/Oct/2019:19:50:27 +0000] "GET /ISTIO_IO_MIRROR_TEST_2 HTTP/1.1" 404 233 "-" "curl/7.35.0"
[2019-11-05 18:48:28 +0000] [1] [INFO] Starting gunicorn 19.9.0
[2019-11-05 18:48:28 +0000] [1] [INFO] Listening at: http://0.0.0.0:80 (1)
[2019-11-05 18:48:28 +0000] [1] [INFO] Using worker: sync
[2019-11-05 18:48:28 +0000] [9] [INFO] Booting worker with pid: 9
127.0.0.1 - - [05/Nov/2019:18:48:56 +0000] "GET /ISTIO_IO_MIRROR_TEST_2 HTTP/1.1" 404 233 "-" "curl/7.35.0"
$endsnippet
$snippet remove_rules.sh syntax="bash"

View File

@ -24,6 +24,9 @@ else
SOURCE_BRANCH_NAME="master"
fi
# TODO: for the 1.4 timeframe, we need to grab the bits from master
SOURCE_BRANCH_NAME=master
SNIPPET_REPO=https://github.com/istio/istio
rm -fr examples/*.snippets.txt

View File

@ -164,7 +164,7 @@ rules:
- apiGroups:
- ""
resources:
- configmaps
- configmaps
- endpoints
- events
- namespaces
@ -172,7 +172,7 @@ rules:
- persistentvolumeclaims
- secrets
- services
- serviceaccounts
- serviceaccounts
verbs:
- '*'
...
@ -239,7 +239,7 @@ spec:
memory: 128Mi
env:
- name: WATCH_NAMESPACE
value: "istio-operator"
value: ""
- name: LEADER_ELECTION_NAMESPACE
valueFrom:
fieldRef: