User guide for istioctl managing webhooks #5162

lei-tang · 2019-10-15T19:49:16Z

A guide of using istioctl to manage webhooks in Istio.

This PR has URLs pointing to: istio/istio#17867 and #5152.
Thus the lint test will fail until these PRs are merged.

Please provide a description for what this PR is for: istio/istio#17061.

Design documents:
[1]https://docs.google.com/document/d/1VHyBre8943USOx_YEVtA18KfEoGTmLT1iBHESO5bzcA/edit#heading=h.qex63c29z2to
[2] https://docs.google.com/document/d/1v8BxI07u-mby5f5rCruwF7odSXgb9G8-C9W5hQtSIAg/edit#heading=h.xw1gqgyqs5b

And to help us figure out who should review this PR, please
put an X in all the areas that this PR affects.

[ ] Configuration Infrastructure
[ ] Docs
[ X] Installation
[ X] Networking
[ ] Performance and Scalability
[ ] Policies and Telemetry
[ X] Security
[ ] Test and Release
[ ] User Experience
[ ] Developer Infrastructure

lei-tang · 2019-10-16T17:11:08Z

/test lint_istio.io

content/en/docs/tasks/security/webhook/index.md

howardjohn · 2019-10-17T23:36:39Z

content/en/docs/tasks/security/webhook/index.md

+
+## Before you begin
+
+* Create a new Kubernetes cluster to run the example in this tutorial.


nit: I don't think this is needed

Creating a new cluster is not strictly needed, but to on the safe side -> avoid affecting an existing cluster.

howardjohn · 2019-10-17T23:37:32Z

content/en/docs/tasks/security/webhook/index.md

+        install/kubernetes/helm/istio > istio-webhook-config.yaml
+    {{< /text >}}
+
+1.  From `istio-webhook-config.yaml`, search `'kind: MutatingWebhookConfiguration'` and save


If this is for more then experimental we need to improve the UX here. If its is just experimental we should make that more clear

Added TODOs to improve the UX here. The document has a warning at the top saying this is an experimental feature.

content/en/docs/tasks/security/webhook/index.md

geeknoid · 2019-10-19T13:17:04Z

content/en/docs/tasks/security/webhook/index.md

+keywords: [security,webhook]
+---
+
+{{< warning >}}


Use the boilerplate for this warning please.

content/en/docs/tasks/security/webhook/index.md

howardjohn · 2019-10-20T15:25:06Z

content/en/docs/tasks/security/webhook/index.md

@@ -0,0 +1,243 @@
+---
+title: Istio Webhook Management
+description: Shows how to manage webhooks in Istio through istioctl.


Can you include why a user would want to do this? Adding this doc, which is a lot of complicated and manual steps, makes it look like this is a required thing to user Istio properly

Added the following explanation why a user would want to do this:
Istio has two webhooks (Galley and Sidecar Injector). In current Istio implementation,
Galley and Sidecar Injector manage their own webhook configurations, which from
security perspective is not recommended because a compromised webhook may conduct
privilege escalation attacks.

This task shows how to use istioctl, instead of Galley and Sidecar Injector, to
manage the webhook configurations of Galley and Sidecar Injector.

lei-tang · 2019-10-23T01:43:20Z

@istio/wg-docs-maintainers-english All review comments have been addressed, can you approve the PR?

rcaballeromx

Please ensure readers can run all commands successfully.

lei-tang · 2019-10-23T22:09:22Z

@rcaballeromx This feature is for Istio with version >= 1.4. Readers can run all commands successfully on Istio with version >= 1.4. The user guide will not be cherrypicked to older Istio versions (e.g., 1.3, 1.2, etc)

lei-tang · 2019-10-25T01:07:36Z

@rcaballeromx Per the discussion, the installation step is removed to decouple the installation from the user guide. Please take a look.

rlenglet

Overall LGTM. Some relatively minor nits.

content/en/docs/setup/install/webhook/index.md

rlenglet

LGTM, thanks!

linsun · 2019-11-07T03:31:57Z

content/en/docs/tasks/security/webhook/index.md

+
+    {{< text plain >}}
+    Error from server: error when creating "invalid-gateway.yaml": admission webhook "pilot.validation.istio.io" denied the request: configuration is invalid: gateway must have at least one server
+    {{< /text >}}


same comment here, i would expect this to fail in the default install also.

need more wording to explain why this is different and how to detect this is running in this new mode.

@linsun How this is different does not belong in the task. We can work on a blog post evaluating both approaches but let's try not to overburden readers with information here.

Added a step to verify that there are no existing webhook configurations for Galley and the sidecar injector before running the webhook enable command.

zjory · 2019-11-07T22:57:11Z

content/en/docs/tasks/security/webhook/index.md

@@ -0,0 +1,231 @@
+---
+title: Istio Webhook Management [Experimental]
+description: Shows how to manage webhooks in Istio through istioctl.


~~Shows~~ How to manage webhooks in Istio through istioctl.

Revised accordingly.

zjory · 2019-11-07T22:59:47Z

content/en/docs/tasks/security/webhook/index.md

+Istio has two webhooks: Galley and the sidecar injector. By default,
+these webhooks manage their own configurations. From a
+security perspective, this default behavior is not recommended because a compromised webhook could then conduct
+privilege escalation attacks.


privileged escalation attacks.

It should be privilege escalation attacks.

zjory · 2019-11-07T23:00:25Z

content/en/docs/tasks/security/webhook/index.md

+security perspective, this default behavior is not recommended because a compromised webhook could then conduct
+privilege escalation attacks.
+
+This task shows how to use `istioctl`, instead of the webhooks, to


This task shows how to use istioctl, instead of ~~the~~ webhooks, to

Revised accordingly.

zjory · 2019-11-07T23:02:20Z

content/en/docs/tasks/security/webhook/index.md

+This task shows how to use `istioctl`, instead of the webhooks, to
+manage their configurations.
+
+## Before you begin


~~## Before you begin~~

Getting started

Revised accordingly.

zjory · 2019-11-07T23:04:14Z

content/en/docs/tasks/security/webhook/index.md

+
+## Check webhook certificates
+
+To display the DNS names in the webhook certificates of Galley and the sidecar injector, we get the secret


To display the DNS names in the webhook certificates of Galley and the sidecar injector, we you need to get the secret

Revised accordingly.

zjory · 2019-11-07T23:08:32Z

content/en/docs/tasks/security/webhook/index.md

+    {{< /text >}}
+
+1.  To check that the sidecar injector webhook is working, verify that the webhook injects a
+sidecar container into an example pod with the following commands:


To Check that the sidecar injector webhook is working by verifying that the webhook injects a
sidecar container into an example pod with the following commands:

The current one is more accurate.

zjory · 2019-11-07T23:09:10Z

content/en/docs/tasks/security/webhook/index.md

+    $ kubectl get pod -n test-injection
+    {{< /text >}}
+
+    The output from the `get pod` command should show the following output. The `2/2` value means that


The output from the get pod command should show the following ~~output~~. The 2/2 value means that

Revised accordingly.

zjory · 2019-11-07T23:11:36Z

content/en/docs/tasks/security/webhook/index.md

+    $ istioctl experimental post-install webhook disable --validation=false --injection-config=istio-sidecar-injector
+    {{< /text >}}
+
+1.  If you name Galleys's configuration `istio-galley`, disable the webhook with the following command:


If you named Galleys's configuration istio-galley, disable the webhook with the following command:

Revised accordingly.

zjory · 2019-11-07T23:17:29Z

content/en/docs/tasks/security/webhook/index.md

+
+After completing this tutorial, you may delete the testing cluster created
+at the beginning of this tutorial. You may also run the following command to delete
+the resources created.


After completing this tutorial, you may delete the testing cluster created
at the beginning of this tutorial. You ~~may also~~ can run the following command to delete
the resources created at the beginning of this tutorial.

Revised accordingly.

zjory

@rcaballeromx Completed review

frankbu · 2019-11-08T00:55:14Z

content/en/docs/tasks/security/webhook/index.md

+    {{< /text >}}
+
+<!-- TODO (lei-tang): improve the UX for obtain MutatingWebhookConfiguration -->
+1.  Open the `istio.yaml` configuration file, search `'kind: MutatingWebhookConfiguration'` and save


Suggested change

1. Open the `istio.yaml` configuration file, search `'kind: MutatingWebhookConfiguration'` and save

1. Open the `istio.yaml` configuration file, search for `kind: MutatingWebhookConfiguration` and save

frankbu · 2019-11-08T00:56:50Z

content/en/docs/tasks/security/webhook/index.md

+    {{< /text >}}
+
+<!-- TODO (lei-tang): improve the UX for obtain ValidatingWebhookConfiguration -->
+1.  Open the `istio.yaml` configuration file, search `'kind: ValidatingWebhookConfiguration'` and save


Suggested change

1. Open the `istio.yaml` configuration file, search `'kind: ValidatingWebhookConfiguration'` and save

1. Open the `istio.yaml` configuration file, search for `kind: ValidatingWebhookConfiguration` and save

frankbu · 2019-11-08T01:00:08Z

content/en/docs/tasks/security/webhook/index.md

+    the webhook injected a sidecar into the example pod:
+
+    {{< text plain >}}
+    NAME    READY   STATUS    RESTARTS   AGE


Suggested change

NAME READY STATUS RESTARTS AGE

NAME READY STATUS RESTARTS AGE

frankbu · 2019-11-08T01:04:12Z

content/en/docs/tasks/security/webhook/index.md

+sidecar container into an example pod with the following commands:
+
+    {{< text bash >}}
+    $ kubectl create namespace test-injection; kubectl label namespaces test-injection istio-injection=enabled


Suggested change

$ kubectl create namespace test-injection; kubectl label namespaces test-injection istio-injection=enabled

$ kubectl create namespace test-injection

$ kubectl label namespaces test-injection istio-injection=enabled

frankbu · 2019-11-08T01:13:44Z

content/en/docs/tasks/security/webhook/index.md

+security perspective, this default behavior is not recommended because a compromised webhook could then conduct
+privilege escalation attacks.
+
+This task shows how to use `istioctl`, instead of webhooks, to


Suggested change

This task shows how to use `istioctl`, instead of webhooks, to

This task shows how to use the new [{{< istioctl >}} x post-install webhook](/docs/reference/commands/istioctl/#istioctl-experimental-post-install-webhook) command to

Revised accordingly.

frankbu · 2019-11-08T01:15:27Z

content/en/docs/tasks/security/webhook/index.md

+privilege escalation attacks.
+
+This task shows how to use `istioctl`, instead of webhooks, to
+manage their configurations.


Suggested change

manage their configurations.

securely manage the configurations of the webhooks.

Revised accordingly.

frankbu

A few suggested changes, but otherwise lgtm.

frankbu · 2019-11-08T04:46:53Z

content/en/docs/tasks/security/webhook/index.md

+    $ istioctl manifest generate > istio.yaml
+    {{< /text >}}
+
+<!-- TODO (lei-tang): improve the UX for obtain MutatingWebhookConfiguration -->


Remove this line. It is causing the numbered list not to render properly.

Done, thanks!

frankbu · 2019-11-08T04:47:32Z

content/en/docs/tasks/security/webhook/index.md

+            istio-injection: enabled
+    {{< /text >}}
+
+<!-- TODO (lei-tang): improve the UX for obtain ValidatingWebhookConfiguration -->


Same as above.

Done, thanks!

lei-tang · 2019-11-08T15:48:30Z

/retest

lei-tang · 2019-11-08T15:49:08Z

/test lint_istio.io

requested changes addressed

lei-tang requested a review from a team as a code owner October 15, 2019 19:49

googlebot added the cla: yes Set by the Google CLA bot to indicate the author of a PR has signed the Google CLA. label Oct 15, 2019

istio-testing added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Oct 15, 2019

lei-tang requested review from costinm, howardjohn, myidpt and rlenglet October 15, 2019 19:49

lei-tang force-pushed the istioctl-webhook branch from 041a962 to 592957e Compare October 15, 2019 20:54

lei-tang mentioned this pull request Oct 17, 2019

Failed to connect to Sidecar Injector and Galley webhooks istio/istio#18009

Closed

howardjohn reviewed Oct 17, 2019

View reviewed changes

geeknoid reviewed Oct 19, 2019

View reviewed changes

content/en/docs/tasks/security/webhook/index.md Show resolved Hide resolved

howardjohn reviewed Oct 20, 2019

View reviewed changes

geeknoid requested a review from rcaballeromx October 23, 2019 03:03

lei-tang added this to the 1.4 milestone Oct 23, 2019

rcaballeromx suggested changes Oct 23, 2019

View reviewed changes

lei-tang requested a review from rcaballeromx October 23, 2019 22:09

rlenglet reviewed Oct 29, 2019

View reviewed changes

rlenglet approved these changes Oct 29, 2019

View reviewed changes

lei-tang added 7 commits October 29, 2019 10:51

User guide for istioctl managing webhooks

ca7538d

Generate the webhook configurations

98add44

Skip long config

48f95ae

Move the task to be under setup/install directory

59384b3

Add jq as a prerequisite

e37ad47

Decouple installation from the user guide

75b795d

Add explanations to config

9aeedaf

linsun reviewed Nov 7, 2019

View reviewed changes

Use istioctl to generate webhook configurations

a04a95b

zjory reviewed Nov 7, 2019

View reviewed changes

Use istioctl to install

985940f

frankbu reviewed Nov 8, 2019

View reviewed changes

Revise the commands

3e1b700

frankbu reviewed Nov 8, 2019

View reviewed changes

frankbu approved these changes Nov 8, 2019

View reviewed changes

Revise the wording

c86150a

frankbu reviewed Nov 8, 2019

View reviewed changes

Remove two comment lines

9b67ba8

istio deleted a comment from lei-tang Nov 8, 2019

istio-testing merged commit b0cdd6f into istio:master Nov 8, 2019


		## Before you begin

		* Create a new Kubernetes cluster to run the example in this tutorial.


		## Check webhook certificates

		To display the DNS names in the webhook certificates of Galley and the sidecar injector, we get the secret

	1. Open the `istio.yaml` configuration file, search `'kind: MutatingWebhookConfiguration'` and save
	1. Open the `istio.yaml` configuration file, search for `kind: MutatingWebhookConfiguration` and save

	NAME READY STATUS RESTARTS AGE
	NAME READY STATUS RESTARTS AGE

	$ kubectl create namespace test-injection; kubectl label namespaces test-injection istio-injection=enabled
	$ kubectl create namespace test-injection
	$ kubectl label namespaces test-injection istio-injection=enabled

	This task shows how to use `istioctl`, instead of webhooks, to
	This task shows how to use the new [{{< istioctl >}} x post-install webhook](/docs/reference/commands/istioctl/#istioctl-experimental-post-install-webhook) command to

	manage their configurations.
	securely manage the configurations of the webhooks.

User guide for istioctl managing webhooks #5162

User guide for istioctl managing webhooks #5162

Uh oh!

Conversation

lei-tang commented Oct 15, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

lei-tang commented Oct 16, 2019

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lei-tang commented Oct 23, 2019

Uh oh!

rcaballeromx left a comment

Choose a reason for hiding this comment

Uh oh!

lei-tang commented Oct 23, 2019

Uh oh!

lei-tang commented Oct 25, 2019

Uh oh!

rlenglet left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

rlenglet left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Getting started

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lei-tang commented Oct 15, 2019 •

edited

Loading

frankbu Nov 8, 2019 •

edited

Loading