mirror of https://github.com/istio/istio.io.git
175 lines
5.2 KiB
Markdown
175 lines
5.2 KiB
Markdown
---
|
|
title: Enabling Istio Auth
|
|
overview: This task shows you how to setup Istio-Auth to provide mutual TLS authentication between services.
|
|
|
|
order: 100
|
|
|
|
layout: docs
|
|
type: markdown
|
|
---
|
|
{% include home.html %}
|
|
|
|
This task shows how to set up Istio Auth in a Kubernetes cluster. You'll learn
|
|
how to:
|
|
|
|
* Enable Istio Auth
|
|
|
|
* Disable Istio Auth
|
|
|
|
* Verify Istio Auth setup
|
|
|
|
|
|
## Before you begin
|
|
|
|
This task assumes you have:
|
|
|
|
* Read the [Istio Auth concepts]({{home}}/docs/concepts/network-and-auth/index.html).
|
|
|
|
* Cloned https://github.com/istio/istio to your local machine
|
|
(Step 1 in [the Istio installation guide](./installing-istio.html#installing-on-an-existing-cluster)).
|
|
|
|
In real world systems, only a single Istio CA should be present in a Kubernetes cluster,
|
|
which is always deployed in a dedicated namespace. The Istio CA issues certificates/keys to
|
|
all pods in the Kubernetes cluster. This offers strong security and automatic trust between namespaces in the same cluster.
|
|
However, this task also instructs how to deploy a namespace-scoped Istio CA,
|
|
for easy setup and clean up during the experiments.
|
|
|
|
## Enabling Istio Auth
|
|
|
|
### Option 1: using per-namespace CA
|
|
|
|
Per namespace CA is convenient for doing experiments.
|
|
Because each Istio CA is scoped within a namespace, Istio CAs in different namespaces will not interfere with each other
|
|
and they are easy to clean up through a single command.
|
|
|
|
We have the YAML files *istio-auth-X.yaml* for deploying all Istio components including Istio CA into the namespace.
|
|
Follow [the Istio installation guide](./installing-istio.html),
|
|
and **choose "If you would like to enable Istio Auth" in step 3**.
|
|
|
|
### Option 2: (recommended) using per-cluster CA
|
|
|
|
Only a single Istio CA is deployed for the Kubernetes cluster, in a dedicated namespace.
|
|
Doing this offers the following benefits:
|
|
|
|
* In the near future, the dedicated namespace will use
|
|
[Kubernetes RBAC](https://kubernetes.io/docs/admin/authorization/rbac/) (beta in Kubernetes V1.6) to provide security
|
|
boundary. This will offer strong security for Istio CA.
|
|
|
|
* Services in the same Kubernetes cluster but different namespaces are able to talk to each other through Istio Auth
|
|
without extra trust setup.
|
|
|
|
#### Deplying CA
|
|
|
|
The following command creates namespace *istio-system* and deploys CA into the namespace:
|
|
|
|
```bash
|
|
kubectl apply -f ./kubernetes/istio-auth/istio-cluster-ca.yaml
|
|
```
|
|
|
|
#### <a name="istioconfig"></a>Enabling Istio Auth in Istio config
|
|
|
|
The following command uncomments the line *authPolicy: MUTUAL_TLS* in the file *kubernetes/istio-X.yaml*,
|
|
and backs up the original file as *istio-X.yaml.bak*
|
|
(*X* corresponds to the Kubernetes server version, choose "15" or "16").
|
|
|
|
```bash
|
|
sed "s/# authPolicy: MUTUAL_TLS/authPolicy: MUTUAL_TLS/" ./kubernetes/istio-X.yaml > ./kubernetes/istio-auth-X.yaml
|
|
```
|
|
|
|
#### Deploying other services
|
|
|
|
Follow [the general Istio installation guide](./installing-istio.html),
|
|
and **choose "If you would like to enable Istio Auth" in step 3**.
|
|
|
|
## Disabling Istio Auth
|
|
|
|
Disabling Istio Auth requires all Istio services and applications to be reconfigured and restarted without auth config.
|
|
|
|
### For per-namespace CA Istio Auth
|
|
|
|
Run the following command to uninstall Istio, and redeploy Istio without auth:
|
|
|
|
```bash
|
|
kubectl delete -f ./kubernetes/istio-auth-X.yaml
|
|
kubectl apply -f ./kubernetes/istio-X.yaml
|
|
```
|
|
|
|
Also, redeploy your application by running:
|
|
|
|
```bash
|
|
kubectl replace -f <(istioctl kube-inject -f <your-app-spec>.yaml)
|
|
```
|
|
|
|
### For per-cluster CA Istio Auth
|
|
|
|
#### Removing per-cluster Istio CA
|
|
|
|
The following command removes Istio CA and its namespace *istio-system*.
|
|
|
|
```bash
|
|
kubectl delete -f ./kubernetes/istio-auth/istio-cluster-ca.yaml
|
|
```
|
|
|
|
#### Redeploying Istio and applications
|
|
|
|
Run the following command to uninstall Istio, and redeploy Istio without auth:
|
|
|
|
```bash
|
|
kubectl delete -f ./kubernetes/istio-auth-X.yaml
|
|
kubectl apply -f ./kubernetes/istio-X.yaml
|
|
```
|
|
|
|
Also, redeploy your application by running:
|
|
|
|
```bash
|
|
kubectl replace -f <(istioctl kube-inject -f <your-app-spec>.yaml)
|
|
```
|
|
|
|
#### Recovering the original config files
|
|
|
|
The following command will recover the original *istio-auth-X.yaml* file.
|
|
|
|
```bash
|
|
git checkout ./kubernetes/istio-auth-X.yaml
|
|
```
|
|
|
|
## Verifying Istio Auth setup
|
|
|
|
The following instructions assume the applications are deployed in the "default" namespace.
|
|
They can be modified for deployments in a separate namespace.
|
|
|
|
Verify AuthPolicy setting in ConfigMap:
|
|
|
|
```bash
|
|
kubectl get configmap istio -o yaml | grep authPolicy
|
|
```
|
|
```bash
|
|
# Istio Auth is enabled if the line "authPolicy: MUTUAL_TLS" is uncommented.
|
|
```
|
|
|
|
Check the certificate and key files are mounted onto the application pod *app-pod*:
|
|
|
|
```bash
|
|
kubectl exec <app-pod> -c proxy -- ls /etc/certs
|
|
```
|
|
```bash
|
|
# Expected files: cert-chain.pem, key.pem and root-cert.pem.
|
|
```
|
|
|
|
When Istio Auth is enabled for a pod, *ssl_context* stanzas should be in the pod's proxy config.
|
|
The following commands verifies the proxy config on *app-pod* has *ssl_context* configured:
|
|
|
|
```bash
|
|
kubectl exec <app-pod> -c proxy -- ls /etc/envoy
|
|
```
|
|
```bash
|
|
# Get the config file named "envoy-revX.json".
|
|
```
|
|
```bash
|
|
kubectl exec <app-pod> -c proxy -- cat /etc/envoy/envoy-revX.json | grep ssl_context
|
|
```
|
|
```bash
|
|
# Expect ssl_context in the output.
|
|
```
|
|
|