mirror of https://github.com/knative/docs.git
Adv. install topic - pluggable components (#542)
* move all install comps to adv file * recovering review comments * filename change * title update * There can be multiple components in a knative package * fix links * new serving version * Update install/Knative-custom-install.md in testing I found that this is not a real namespace so removing * Update packages in table * review feedback, 0.2.1 eventing, eventsource lists * edit Istio steps around admission controller * fix indentation * Recover networking related comments
This commit is contained in:
RichieEscarez
Knative Prow Robot
parent
c5fefdb08d
commit
d04370f023
|
|
@ -0,0 +1,316 @@
|
|||
# Performing a Custom Knative Installation
|
||||
|
||||
Use this guide to perform custom installations of Knative on your existing
|
||||
Kubernetes clusters. Knative's pluggable components allow you to
|
||||
install only what you want in each of your clusters.
|
||||
|
||||
The steps covered in the guide are for advanced operators who want to
|
||||
customize each Knative installation. Installing individual Knative components
|
||||
requires that you to run multiple and separate installation commands.
|
||||
|
||||
## Before you begin
|
||||
|
||||
* If you are new to Knative, you should instead [install one of the default
|
||||
installation packages](./README.md). Follow the host specific Knative installation
|
||||
instructions to help you get up and running with the least effort. Installing
|
||||
a default package also ensures that you can run all the
|
||||
[Knative Serving Samples](https://github.com/knative/docs/blob/master/serving/samples/README.md).
|
||||
|
||||
* The steps in this guide use `bash` for the MacOS or Linux environment; for Windows,
|
||||
some commands might need adjustment.
|
||||
|
||||
* This guide assumes that you have an existing Kubernetes cluster,
|
||||
on which you're comfortable installing and running _alpha_ level software.
|
||||
|
||||
* Kubernetes requirements:
|
||||
|
||||
* Your Kubernetes cluster version must be v1.10 or newer.
|
||||
|
||||
* Your version of the
|
||||
[`kubectl` CLI tool](https://kubernetes.io/docs/tasks/tools/install-kubectl/)
|
||||
must be v1.10 or newer.
|
||||
|
||||
## Installing Istio
|
||||
|
||||
Knative depends on [Istio](https://istio.io/docs/concepts/what-is-istio/) for
|
||||
traffic routing and ingress. You have to option of injecting Istio sidecars and
|
||||
enabling the Istio service mesh, but it's not required for certain Knative component.
|
||||
|
||||
You should first install the `istio-crds.yaml` package to ensure that the Istio
|
||||
[Custom Resource Definitions (CRD)](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/)
|
||||
are created before installing one of the Istio install packages.
|
||||
|
||||
### Choosing an Istio installation package
|
||||
|
||||
You can Istio with or without a service mesh:
|
||||
|
||||
* *automatic sidecar injection*: Enables the Istio service mesh by
|
||||
[automatically injecting the Istio sidecars](https://istio.io/docs/setup/kubernetes/sidecar-injection/#automatic-sidecar-injection).
|
||||
The sidecars are injected into each pod of your cluster as each pod is created.
|
||||
|
||||
* *manual sidecar injection*: Provides your Knative installation with traffic
|
||||
routing and ingress, without the Istio service mesh. You do have the option of
|
||||
later enabling the service mesh if you
|
||||
[manually inject the Istio sidecars](https://istio.io/docs/setup/kubernetes/sidecar-injection/#manual-sidecar-injection).
|
||||
|
||||
If you are just getting started with Knative, you should choose automatic
|
||||
sidecar injection and enable the Istio service mesh.
|
||||
|
||||
Due to current dependencies, some installable Knative options require the Istio
|
||||
service mesh. You must install the `istio.yaml` package to enable automatic
|
||||
sidecar injection to install the following options:
|
||||
|
||||
* [Knative Eventing](https://github.com/knative/eventing)
|
||||
* [Knative Eventing Sources](https://github.com/knative/eventing-sources)
|
||||
* [Observability plugins](../serving/installing-logging-metrics-traces.md)
|
||||
|
||||
#### Istio installation packages
|
||||
|
||||
| Istio Package Filename | Description |
|
||||
| ---------------------- | ----------------- |
|
||||
| [`istio-crds.yaml`][a] | Initially create CRDs before installing Istio. |
|
||||
| [`istio.yaml`][b] | Install Istio with service mesh enabled (automatic sidecar injection). |
|
||||
| [`istio-lean.yaml`][c] | Install Istio and disable the service mesh by default. |
|
||||
|
||||
[a]: https://github.com/knative/serving/releases/download/v0.2.3/istio-crds.yaml
|
||||
[b]: https://github.com/knative/serving/releases/download/v0.2.3/istio.yaml
|
||||
[c]: https://github.com/knative/serving/releases/download/v0.2.3/istio-lean.yaml
|
||||
|
||||
### Installing Istio installation packages
|
||||
|
||||
1. If you choose to install the Istio service mesh with automatic sidecar
|
||||
injection, you must ensure that the
|
||||
[`MutatingAdmissionWebhook` admission controller](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.10/#mutatingwebhookconfiguration-v1beta1-admissionregistration-k8s-io)
|
||||
is enabled on your cluster by running the following command:
|
||||
|
||||
```bash
|
||||
kubectl api-versions | grep admissionregistration
|
||||
```
|
||||
|
||||
Result:
|
||||
```bash
|
||||
admissionregistration.k8s.io/v1beta1
|
||||
```
|
||||
|
||||
If `admissionregistration.k8s.io/v1beta1` is not listed, follow the
|
||||
[Kubernetes instructions about enabling the `MutatingAdmissionWebhook` admission controller](https://kubernetes.io/docs/admin/admission-controllers/#how-do-i-turn-on-an-admission-controller).
|
||||
|
||||
For example, you add `--enable-admission-plugins=MutatingAdmissionWebhook`
|
||||
to the `/etc/kubernetes/manifests/kube-apiserver.yaml` file.
|
||||
|
||||
1. Create the Istio CRDs on your cluster:
|
||||
```bash
|
||||
kubectl apply --filename https://github.com/knative/serving/releases/download/v0.2.3/istio-crds.yaml
|
||||
```
|
||||
|
||||
1. Install Istio by specifying the package's path and filename in the `kubectl apply` command:
|
||||
```bash
|
||||
kubectl apply --filename https://github.com/knative/serving/releases/download/v0.2.3/[FILENAME].yaml
|
||||
```
|
||||
|
||||
where `[FILENAME]` is the name of the Istio package that you want to install. Examples:
|
||||
* `istio.yaml`
|
||||
* `istio-lean.yaml`
|
||||
|
||||
1. If you chose to install the Istio service mesh with automatic sidecar injection, you must
|
||||
label the default namespace with `istio-injection=enabled`:
|
||||
```bash
|
||||
kubectl label namespace default istio-injection=enabled
|
||||
```
|
||||
|
||||
Important: You should set the `istio-injection` namespace, if you intend on
|
||||
later enabling the Istio service mesh through manual sidecar injection.
|
||||
|
||||
1. View the status of your Istio installation. It might take a few
|
||||
seconds so rerun the following command until all of the pods show a
|
||||
`STATUS` of `Running` or `Completed`:
|
||||
```bash
|
||||
kubectl get pods --namespace istio-system
|
||||
```
|
||||
|
||||
> Tip: You can append the `--watch` flag to the `kubectl get` commands to
|
||||
view the pod status in realtime. You use `CTRL + C` to exit watch mode.
|
||||
|
||||
## Installing Knative components
|
||||
|
||||
You can install each Knative component independently or use the default packages
|
||||
to install multiple components. The individual component packages exclude
|
||||
an observability plugin but you have the option to install one later.
|
||||
|
||||
### Choosing Knative installation packages
|
||||
|
||||
The following Knative installation packages are available:
|
||||
|
||||
* **Multiple Component Bundle**:
|
||||
* https://github.com/knative/serving/releases/download/v0.2.3/release.yaml
|
||||
* https://github.com/knative/serving/releases/download/v0.2.3/release-no-mon.yaml
|
||||
* https://github.com/knative/serving/releases/download/v0.2.3/release-lite.yaml
|
||||
|
||||
If you are new to Knative, you should install a bundle to get started. More
|
||||
information about installing a bundle are in the [install guides](./README.md).
|
||||
|
||||
* **Build Component**:
|
||||
* https://github.com/knative/build/releases/download/v0.2.0/release.yaml
|
||||
* **Eventing Component**:
|
||||
* https://github.com/knative/eventing/releases/download/v0.2.1/release.yaml
|
||||
* https://github.com/knative/eventing/releases/download/v0.2.1/eventing.yaml
|
||||
* https://github.com/knative/eventing-sources/releases/download/v0.2.1/release.yaml
|
||||
* https://github.com/knative/eventing-sources/releases/download/v0.2.1/release-with-gcppubsub.yaml
|
||||
* **Serving Component**:
|
||||
* https://github.com/knative/serving/releases/download/v0.2.3/serving.yaml
|
||||
|
||||
#### Install package details and options
|
||||
|
||||
The following table includes details about the available Knative installation packages from the Knative repositories:
|
||||
|
||||
* [Serving][1]
|
||||
* [Build][3]
|
||||
* [Eventing][4]
|
||||
* [Eventing Sources][5]
|
||||
|
||||
| Knative Package Filename | Serving Component | Observability Plugin* |Build Component | Eventing Component | Eventing Notes |
|
||||
| ------------------------ | ----------------- | --------------------- | --------------- | ------------------ | ---------------- |
|
||||
| **knative/serving** ||||||
|
||||
| [`release.yaml`][1.1] | Included | [ELK stack][2] with [Prometheus][2.1] and [Grafana][2.2]* | Included | - | - |
|
||||
| [`release-no-mon.yaml`][1.2] | Included | - |Included | - | - |
|
||||
| [`release-lite.yaml`][1.3] | Included | [Prometheus][2.1] and [Grafana][2.2]* | Included | - | |
|
||||
| [`serving.yaml`][1.4] | Included | - | - | - | - |
|
||||
| [`build.yaml`][1.5] (copied from [knative/build][3]) | - | - | Included | - | - |
|
||||
| **knative/build** ||||||
|
||||
|[`release.yaml`][3.1] | - | - | Included | - | - |
|
||||
| **knative/eventing** ||||||
|
||||
| [`release.yaml`][4.1] | *Required* | - | - | Included | Includes the in-memory channel provisioner. |
|
||||
| [`eventing.yaml`][4.2] | *Required* | - | - | Included | No channel provisioner. |
|
||||
|[`in-memory-channel.yaml`][4.3] | *Required* | - | - | *Required* | Only the in-memory channel provisioner. |
|
||||
| [`kafka.yaml`][4.4] | *Required* | - | - | *Required* | Only the Kafka channel provisioner. |
|
||||
| **knative/eventing-sources** ||||||
|
||||
|[`release.yaml`][5.1] | *Required* | - | - | *Required* | Source types: [Kubernetes][6], [GitHub][6.1], [Container image][6.3] |
|
||||
| [`release-with-gcppubsub.yaml`][5.2] | *Required* | - | - | *Required* | Source types: [Kubernetes][6], [GitHub][6.1], [Container image][6.3], [PubSub][6.4] |
|
||||
| [`message-dumper.yaml`][5.3] | *Required* | - | - | *Required* | Event logging service for debugging. |
|
||||
|
||||
_*_ See [Installing observability plugins](../serving/installing-logging-metrics-traces.md)
|
||||
for details about the supported plugins and how to add monitoring, logging, and
|
||||
tracing to your cluster.
|
||||
|
||||
[1]: https://github.com/knative/serving/releases/tag/v0.2.2
|
||||
[1.1]: https://github.com/knative/serving/releases/download/v0.2.3/release.yaml
|
||||
[1.2]: https://github.com/knative/serving/releases/download/v0.2.3/release-no-mon.yaml
|
||||
[1.3]: https://github.com/knative/serving/releases/download/v0.2.3/release-lite.yaml
|
||||
[1.4]: https://github.com/knative/serving/releases/download/v0.2.3/serving.yaml
|
||||
[1.5]: https://github.com/knative/serving/releases/download/v0.2.3/build.yaml
|
||||
|
||||
[2]: https://www.elastic.co/elk-stack
|
||||
[2.1]: https://prometheus.io
|
||||
[2.2]: https://grafana.com
|
||||
|
||||
[3]: https://github.com/knative/build/releases/tag/v0.2.0
|
||||
[3.1]: https://github.com/knative/build/releases/download/v0.2.0/release.yaml
|
||||
|
||||
[4]: https://github.com/knative/eventing/releases/tag/v0.2.1
|
||||
[4.1]: https://github.com/knative/eventing/releases/download/v0.2.1/release.yaml
|
||||
[4.2]: https://github.com/knative/eventing/releases/download/v0.2.1/eventing.yaml
|
||||
[4.3]: https://github.com/knative/eventing/releases/download/v0.2.1/in-memory-channel.yaml
|
||||
[4.4]: https://github.com/knative/eventing/releases/download/v0.2.1/kafka.yaml
|
||||
|
||||
[5]: https://github.com/knative/eventing-sources/releases/tag/v0.2.1
|
||||
[5.1]: https://github.com/knative/eventing-sources/releases/download/v0.2.1/release.yaml
|
||||
[5.2]: https://github.com/knative/eventing-sources/releases/download/v0.2.1/release-with-gcppubsub.yaml
|
||||
[5.3]: https://github.com/knative/eventing-sources/releases/download/v0.2.1/message-dumper.yaml
|
||||
|
||||
[6]: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.12/#event-v1-core
|
||||
[6.1]: https://developer.github.com/v3/activity/events/types/
|
||||
[6.3]: https://github.com/knative/docs/tree/master/eventing#containersource
|
||||
[6.4]: https://cloud.google.com/pubsub/
|
||||
|
||||
### Installing Knative packages
|
||||
|
||||
**Tip**: From the table above, copy and paste the URL and package filename into
|
||||
the commands below.
|
||||
|
||||
1. To install a Knative package by specifying the package's path and filename
|
||||
in the `kubectl apply` command:
|
||||
|
||||
* To install an individual package:
|
||||
```bash
|
||||
kubectl apply --filename [INSTALL_PACKAGE]
|
||||
```
|
||||
|
||||
* To install multiple packages, append additional `--filename [INSTALL_PACKAGE]`
|
||||
flags to the `kubectl apply` command:
|
||||
```bash
|
||||
kubectl apply --filename [INSTALL_PACKAGE] --filename [INSTALL_PACKAGE] \
|
||||
--filename [INSTALL_PACKAGE]
|
||||
```
|
||||
|
||||
where [`INSTALL_PACKAGE`] is the URL path and filename of the a Knative installation package:
|
||||
|
||||
`https://github.com/knative/[COMPONENT]/releases/download/[VERSION]/[FILENAME].yaml`
|
||||
|
||||
and `[COMPONENT]`, `[VERSION]`, and `[FILENAME]` are the Knative component, release version, and filename of the installable resource. Examples:
|
||||
* `https://github.com/knative/build/releases/download/v0.2.0/release.yaml`
|
||||
* `https://github.com/knative/eventing/releases/download/v0.2.1/eventing.yaml`
|
||||
* `https://github.com/knative/eventing-sources/releases/download/v0.2.1/release.yaml`
|
||||
* `https://github.com/knative/serving/releases/download/v0.2.3/serving.yaml`
|
||||
|
||||
|
||||
**Example install commands:**
|
||||
|
||||
* To install the Knative Serving and Build bundle:
|
||||
|
||||
```bash
|
||||
kubectl apply --filename https://github.com/knative/serving/releases/download/v0.2.3/release.yaml
|
||||
```
|
||||
|
||||
* To install all three Knative components without an observibility plugin:
|
||||
|
||||
```bash
|
||||
kubectl apply --filename https://github.com/knative/build/releases/download/v0.2.0/release.yaml \
|
||||
--filename https://github.com/knative/eventing/releases/download/v0.2.1/eventing.yaml \
|
||||
--filename https://github.com/knative/serving/releases/download/v0.2.3/serving.yaml
|
||||
```
|
||||
|
||||
1. Depending on what you choose to install, you view the status of your
|
||||
installation by running one or more of the following commands. It
|
||||
might take a few seconds so rerun the commands until all of the components
|
||||
show a `STATUS` of `Running`:
|
||||
|
||||
```bash
|
||||
kubectl get pods --namespace knative-build
|
||||
kubectl get pods --namespace knative-eventing
|
||||
kubectl get pods --namespace knative-sources
|
||||
kubectl get pods --namespace knative-serving
|
||||
```
|
||||
|
||||
> Tip: You can append the `--watch` flag to the `kubectl get` commands to
|
||||
view the pod status in realtime. You use `CTRL + C` to exit watch mode.
|
||||
|
||||
1. If you installed a package that includes an observability plugin, run the following
|
||||
command to ensure that the `knative-monitoring` pods show a `STATUS` of `Running`:
|
||||
|
||||
```bash
|
||||
kubectl get pods --namespace knative-monitoring
|
||||
```
|
||||
|
||||
You are now ready to deploy an app, create a build, or start sending and receiving
|
||||
events in your Knative cluster.
|
||||
|
||||
## What's next
|
||||
|
||||
If you want to add monitoring, logging, and tracing support to your cluster, see
|
||||
[Installing observability plugins](../serving/installing-logging-metrics-traces.md)
|
||||
for details about the supported plugins.
|
||||
|
||||
Depending on the Knative components you installed, you can use the following guides
|
||||
to help you get started with Knative:
|
||||
|
||||
* [Getting Started with Knative App Deployment](./getting-started-knative-app.md).
|
||||
|
||||
* [Knative Serving sample apps](../serving/samples/README.md).
|
||||
|
||||
* [Creating a simple Knative Build](../build/creating-builds.md).
|
||||
|
||||
* [Knative Build templates](https://github.com/knative/build-templates).
|
||||
|
||||
* [Knative Eventing overview](../eventing/README.md).
|
||||
|
||||
* [Knative Eventing code samples](../eventing/samples).
|
||||
Loading…
Reference in New Issue