mirror of https://github.com/istio/istio.io.git
Add instructions on installing Istio for vms (#7248)
* Add instructions on installing Istio for vms * Address review comments workaround netlify * Fix cert management link * Remove /var/run/secrets from document * Address linting problems rebase for netlify failure * Address review comments - not quite functional This change addresses all reviewer comments, but does not address my personal testing. That is the next commit in this PR:) * Address reviewier comments * One small improvement to the make command * Address reviewer comments. * Address reviewer comments and lintian problems * Fix spellING errors. * few linting errors. * Self review. * Add a plugin ca cert reference to individual CSOs. force push to work around netlify issue * Move from setup/install/multicluster * Rebase to pick up cert-management directory change netlify rebase * Address @rshriram comment by adding a banner force rebase to force netlify to build * Address reviewer comments. * Address reviewer comments * Address reviewer comments rebase for netlify * Address reviewer comments * Address @frankb 's comments. force push for netlify * Address reviewer comments. * Prefix WORK_DIR with $HOME instead of $WORK_DIR. :) netliffy rebase * Address most of @smawson's comments * Fix linting error * Address reviewer comments. rebase for netlify * Fix linting errors * Add tip explaining that only one VM can be registered * Fix linting errors. * Resolve reviewer comments.
This commit is contained in:
Steven Dake
GitHub
parent
6b9fa8be94
commit
f8ea259306
|
|
@ -0,0 +1,226 @@
|
|||
---
|
||||
title: Virtual Machine Installation
|
||||
description: Deploy istio and connect a virtual machine to it.
|
||||
weight: 40
|
||||
keywords:
|
||||
- kubernetes
|
||||
- virtual-machine
|
||||
- gateways
|
||||
- vms
|
||||
---
|
||||
|
||||
Follow this guide to deploy Istio and connect a virtual machine to it.
|
||||
|
||||
{{< warning >}}
|
||||
This guide has a requirement that the user is using a [plugin root CA](/docs/tasks/security/cert-management/plugin-ca-cert/)
|
||||
and has configured Istio as an intermediate CA.
|
||||
{{< /warning >}}
|
||||
|
||||
{{< tip >}}
|
||||
This guide is tested and validated. The Istio authors feel this guide is suitable for experimentation
|
||||
but not production. Like all alpha features, this guide is subject to change.
|
||||
{{< /tip >}}
|
||||
|
||||
## Prerequisites
|
||||
|
||||
1. [Download the Istio release](/docs/setup/getting-started/#download)
|
||||
1. Perform any necessary [platform-specific setup](/docs/setup/platform-setup/)
|
||||
1. Check the requirements [for Pods and Services](/docs/ops/deployment/requirements/)
|
||||
1. Virtual machines must have IP connectivity to the ingress gateway in the connecting mesh, and optionally every pod in the mesh via L3 networking if enhanced performance is desired.
|
||||
|
||||
## Prepare the guide environment
|
||||
|
||||
1. Set the environment variables `"${ISTIO_DIR}"`, `"${WORK_DIR}"`, your cluster
|
||||
name, and the service namespace. Ensure `"${WORK_DIR}"` is prefixed with `"${HOME}"`
|
||||
(e.g. `WORK_DIR="${HOME}"/vmintegration`).
|
||||
|
||||
{{< text bash >}}
|
||||
$ ISTIO_DIR="<the directory containing an unarchived version of Istio>"
|
||||
$ CLUSTER_NAME="<the name of your cluster>"
|
||||
$ SERVICE_NAMESPACE="<the name of your service namespace>"
|
||||
$ WORK_DIR="<a certificate working directory>"
|
||||
{{< /text >}}
|
||||
|
||||
1. Create the `"${WORK_DIR}"/"${CLUSTER_NAME}"/"${SERVICE_NAMESPACE}"` working directories.
|
||||
|
||||
{{< text bash >}}
|
||||
$ mkdir -p "${WORK_DIR}"/"${CLUSTER_NAME}"/"${SERVICE_NAMESPACE}"
|
||||
{{< /text >}}
|
||||
|
||||
## Create certificates for use with the virtual machine and Istio control plane
|
||||
|
||||
{{< tip >}}
|
||||
This `Makefile` is limited to creating one virtual machine certificate per cluster. The Istio authors
|
||||
expect operators to read and understand this guide to formulate their own plans for creating and
|
||||
managing virtual machines. It is important for you to read and understand this `Makefile` for any
|
||||
deployment you place into production.
|
||||
{{< /tip >}}
|
||||
|
||||
1. Execute the following commands to create certificates for use by Istio. See
|
||||
[Certificate Authority (CA) certificates](/docs/tasks/security/cert-management/plugin-ca-cert/)
|
||||
for more details on configuring an external CA. The `NAME` variable is
|
||||
used during certificate generation to uniquely identify clusters. The
|
||||
`NAMESPACE` variable identifies the namespace where the virtual machine
|
||||
connectivity is hosted.
|
||||
|
||||
{{< text bash >}}
|
||||
$ cd "${WORK_DIR}"
|
||||
$ make -f "${ISTIO_DIR}"/samples/certs/Makefile NAME="${CLUSTER_NAME}" NAMESPACE="${SERVICE_NAMESPACE}" "${CLUSTER_NAME}"-certs-wl
|
||||
{{< /text >}}
|
||||
|
||||
## Install the Istio control plane
|
||||
|
||||
The Istio control plane must be installed with virtual machine integration enabled (`values.global.meshExpansion.enabled: true`).
|
||||
|
||||
1. Register the certificates needed for installation.
|
||||
|
||||
{{< text bash >}}
|
||||
$ kubectl create namespace istio-system
|
||||
$ kubectl create secret generic cacerts -n istio-system \
|
||||
--from-file="${WORK_DIR}"/"${CLUSTER_NAME}"/ca-cert.pem \
|
||||
--from-file="${WORK_DIR}"/"${CLUSTER_NAME}"/ca-key.pem \
|
||||
--from-file="${WORK_DIR}"/"${CLUSTER_NAME}"/root-cert.pem \
|
||||
--from-file="${WORK_DIR}"/"${CLUSTER_NAME}"/cert-chain.pem
|
||||
{{< /text >}}
|
||||
|
||||
1. Create the install `IstioOperator` custom resource:
|
||||
|
||||
{{< text bash >}}
|
||||
$ cat <<EOF> "${WORK_DIR}"/vmintegration.yaml
|
||||
apiVersion: install.istio.io/v1alpha1
|
||||
metadata:
|
||||
namespace: istio-system
|
||||
name: example-istiocontrolplane
|
||||
kind: IstioOperator
|
||||
spec:
|
||||
values:
|
||||
global:
|
||||
meshExpansion:
|
||||
enabled: true
|
||||
EOF
|
||||
{{< /text >}}
|
||||
|
||||
1. Install or upgrade Istio with virtual machine integration features enabled.
|
||||
|
||||
{{< text bash >}}
|
||||
$ istioctl install -f "${WORK_DIR}"/vmintegration.yaml
|
||||
{{< /text >}}
|
||||
|
||||
## Create files to transfer to the virtual machine
|
||||
|
||||
1. Make a copy of files to copy to the virtual machine
|
||||
|
||||
{{< text bash >}}
|
||||
$ cp -a "${WORK_DIR}"/"${CLUSTER_NAME}"/"{SERVICE_NAMESPACE}"/ca-cert.pem "${WORK_DIR}"/"{CLUSTER_NAME}"/"${SERVICE_NAMESPACE}"/COPY_TO_VIRTUAL_MACHINE
|
||||
$ cp -a "${WORK_DIR}"/"${CLUSTER_NAME}"/"{SERVICE_NAMESPACE}"/key.pem "${WORK_DIR}"/"{CLUSTER_NAME}"/"${SERVICE_NAMESPACE}"/COPY_TO_VIRTUAL_MACHINE
|
||||
$ cp -a "${WORK_DIR}"/"${CLUSTER_NAME}"/"{SERVICE_NAMESPACE}"/root-cert.pem "${WORK_DIR}"/"{CLUSTER_NAME}"/"${SERVICE_NAMESPACE}"/COPY_TO_VIRTUAL_MACHINE
|
||||
$ cp -a "${WORK_DIR}"/"${CLUSTER_NAME}"/"{SERVICE_NAMESPACE}"/workload-cert-chain.pem "${WORK_DIR}"/"{CLUSTER_NAME}"/"${SERVICE_NAMESPACE}"/COPY_TO_VIRTUAL_MACHINE/cert-chain.pem
|
||||
{{< /text >}}
|
||||
|
||||
1. Generate a `cluster.env` configuration file that informs the virtual machine
|
||||
deployment which network CIDR to capture and redirect to the Kubernetes
|
||||
cluster:
|
||||
|
||||
{{< text bash >}}
|
||||
$ ISTIO_SERVICE_CIDR=$(echo '{"apiVersion":"v1","kind":"Service","metadata":{"name":"tst"},"spec":{"clusterIP":"1.1.1.1","ports":[{"port":443}]}}' | kubectl apply -f - 2>&1 | sed 's/.*valid IPs is //')
|
||||
$ echo ISTIO_SERVICE_CIDR=$ISTIO_SERVICE_CIDR > "${WORK_DIR}"/"${SERVICE_NAMESPACE}"/COPY_TO_VIRTUAL_MACHINE/cluster.env
|
||||
{{< /text >}}
|
||||
|
||||
1. Optionally configure configure a select set of ports for exposure from the
|
||||
virtual machine. If you do not apply this optional step, all outbound traffic
|
||||
on all ports is sent to the Kubernetes cluster. You may wish to send some
|
||||
traffic on specific ports to other destinations. This example shows enabling
|
||||
ports `3306` and `8080` for capture by Istio virtual machine integration and
|
||||
transmission to Kubernetes. All other ports are sent over the default gateway
|
||||
of the virtual machine.
|
||||
|
||||
{{< text bash >}}
|
||||
$ echo "ISTIO_INBOUND_PORTS=3306,8080" >> "${WORK_DIR}"/"${CLUSTER_NAME}"/"${SERVICE_NAMESPACE}"/"$COPY_TO_VIRTUAL_MACHINE/cluster.env
|
||||
{{< /text >}}
|
||||
|
||||
1. Add an IP address that represents Istiod. Replace `${INGRESS_HOST}` with the
|
||||
ingress gateway service of istiod. Revisit
|
||||
[Determining the ingress host and ports](/docs/tasks/traffic-management/ingress/ingress-control/#determining-the-ingress-ip-and-ports) to set the environment variable `${INGRESS_HOST}`.
|
||||
|
||||
{{< text bash >}}
|
||||
$ echo "${INGRESS_HOST} istiod.istio-system.svc" > $"{WORK_DIR}"/"${CLUSTER_NAME}"/"{SERVICE_NAMESPACE}"/hosts-addendum
|
||||
{{< /text >}}
|
||||
|
||||
{{< idea >}}
|
||||
A sophisticated option involves configuring DNS within the virtual
|
||||
machine to reference an external DNS server. This option is beyond
|
||||
the scope of this document.
|
||||
{{< /idea >}}
|
||||
|
||||
## Configure the virtual machine
|
||||
|
||||
Run the following commands on the virtual machine you want to add to the Istio mesh:
|
||||
|
||||
1. Securely transfer the files from `"${WORK_DIR}"/"${CLUSTER_NAME}"/"${SERVICE_NAMESPACE}"/COPY_TO_VIRTUAL_MACHINE`
|
||||
to the virtual machine. How you choose to securely transfer those files should be done with consideration for
|
||||
your information security policies.
|
||||
|
||||
1. Update the cache of package updates for your `deb` packaged distro.
|
||||
|
||||
{{< text bash >}}
|
||||
$ sudo apt -y update
|
||||
{{< /text >}}
|
||||
|
||||
1. Upgrade the `deb` packaged distro to ensure all latest security packages are applied.
|
||||
|
||||
{{< text bash >}}
|
||||
$ sudo apt -y upgrade
|
||||
{{< /text >}}
|
||||
|
||||
1. Install the `deb` package containing the Istio virtual machine integration runtime.
|
||||
|
||||
{{< text bash >}}
|
||||
$ curl -LO https://storage.googleapis.com/istio-release/releases/{{< istio_full_version >}}/deb/istio-sidecar.deb
|
||||
$ sudo dpkg -i istio-sidecar.deb
|
||||
{{< /text >}}
|
||||
|
||||
1. Install `root-cert.pem`, `key.pem` and `cert-chain.pem` within the directory `/etc/certs/`.
|
||||
|
||||
{{< text bash >}}
|
||||
$ sudo mkdir -p /etc/certs
|
||||
$ sudo cp {root-cert.pem,cert-chain.pem,key.pem} /etc/certs
|
||||
{{< /text >}}
|
||||
|
||||
1. Install `cluster.env` within `/var/lib/istio/envoy/`.
|
||||
|
||||
{{< text bash >}}
|
||||
$ sudo cp cluster.env /var/lib/istio/envoy
|
||||
{{< /text >}}
|
||||
|
||||
1. Add the istiod host to `/etc/hosts`.
|
||||
|
||||
{{< text bash >}}
|
||||
$ sudo cat hosts-addendum >> /etc/hosts
|
||||
{{< /text >}}
|
||||
|
||||
1. Transfer ownership of the files in `/etc/certs/` and `/var/lib/istio/envoy/` to the Istio proxy.
|
||||
|
||||
{{< text bash >}}
|
||||
$ sudo chown -R istio-proxy /etc/certs /var/lib/istio/envoy
|
||||
{{< /text >}}
|
||||
|
||||
1. Start Istio within the virtual machine.
|
||||
|
||||
{{< text bash >}}
|
||||
$ sudo systemctl start istio
|
||||
{{< /text >}}
|
||||
|
||||
## Uninstall
|
||||
|
||||
To uninstall Istio, run the following command:
|
||||
|
||||
{{< text bash >}}
|
||||
$ istioctl manifest generate -f "${WORK_DIR}"/vmintegration.yaml | kubectl delete -f -
|
||||
{{< /text >}}
|
||||
|
||||
The control plane namespace (e.g., `istio-system`) is not removed by default.
|
||||
If no longer needed, use the following command to remove it:
|
||||
|
||||
{{< text bash >}}
|
||||
$ kubectl delete namespace istio-system
|
||||
{{< /text >}}
|
||||
Loading…
Reference in New Issue