Skip to content

Latest commit

 

History

History
351 lines (264 loc) · 18.2 KB

Knative-custom-install.md

File metadata and controls

351 lines (264 loc) · 18.2 KB

Performing a Custom Knative Installation

Use this guide to perform a custom installation of Knative on an existing Kubernetes cluster. Knative's pluggable components allow you to install only what you need.

The steps covered in this guide are for advanced operators who want to customize each Knative installation. Installing individual Knative components requires you to run multiple installation commands.

Before you begin

  • If you are new to Knative, you should instead follow one of the platform-specific installation guides to help you get up and running quickly.

  • 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.11 or newer.

    • Your version of the kubectl CLI tool must be v1.10 or newer.

Installing Istio

Note: Gloo is available as an alternative to Istio. Gloo is not currently compatible with the Knative Eventing component. Click here to install Knative with Gloo.

Knative depends on Istio for traffic routing and ingress. You have the option of injecting Istio sidecars and enabling the Istio service mesh, but it's not required for all Knative components.

You should first install the istio-crds.yaml file to ensure that the Istio Custom Resource Definitions (CRD) are created before installing Istio.

Choosing an Istio installation

You can Istio with or without a service mesh:

  • automatic sidecar injection: Enables the Istio service mesh by automatically injecting the Istio sidecars. 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.

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. If you install any of the following options, you must install istio.yaml so that automatic sidecar injection is enabled:

Istio installation options

Istio Install Filename Description
istio-crds.yaml† Creates CRDs before installing Istio.
istio.yaml† Install Istio with service mesh enabled (automatic sidecar injection).
istio-lean.yaml Install Istio and disable the service mesh by default.

† These are the recommended standard install files suitable for most use cases.

Installing Istio

  1. If you choose to install the Istio service mesh with automatic sidecar injection, you must ensure that the MutatingAdmissionWebhook admission controller is enabled on your cluster by running the following command:

    kubectl api-versions | grep admissionregistration

    Result:

    admissionregistration.k8s.io/v1beta1

    If admissionregistration.k8s.io/v1beta1 is not listed, follow the Kubernetes instructions about enabling the MutatingAdmissionWebhook admission controller.

    For example, you add --enable-admission-plugins=MutatingAdmissionWebhook to the /etc/kubernetes/manifests/kube-apiserver.yaml file.

  2. Create the Istio CRDs on your cluster:

    kubectl apply --filename https://github.com/knative/serving/releases/download/v0.3.0/istio-crds.yaml

  3. Install Istio by specifying the filename in the kubectl apply command:

    kubectl apply --filename https://github.com/knative/serving/releases/download/v0.3.0/[FILENAME].yaml

    where [FILENAME] is the name of the Istio file that you want to install. Examples:

    • istio.yaml
    • istio-lean.yaml

  4. If you chose to install the Istio service mesh with automatic sidecar injection, you must label the default namespace with istio-injection=enabled:

    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.

  5. 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:

    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

Each Knative component must be installed individually. You can decide which components and observability plugins to install based on what you plan to do with Knative.

Choosing Knative installation files

The following Knative installation files are available:

Install details and options

The following table includes details about the available Knative installation files from the Knative repositories:

Knative Install Filename Notes Dependencies
knative/serving
serving.yaml† Installs the Serving component.
monitoring.yaml† Installs the ELK stack, Prometheus, Grafana, and Zipkin* Serving component
monitoring-logs-elasticsearch.yaml Installs only the ELK stack* Serving component
monitoring-metrics-prometheus.yaml Installs only Prometheus* Serving component
monitoring-tracing-zipkin.yaml Installs only Zipkin.* Serving component, ELK stack (monitoring-logs-elasticsearch.yaml)
monitoring-tracing-zipkin-in-mem.yaml Installs only Zipkin in-memory* Serving component
knative/build
release.yaml† Installs the Build component.
knative/eventing
release.yaml† Installs the Eventing component. Includes the in-memory channel provisioner. Serving component
eventing.yaml Installs the Eventing component. Does not include the in-memory channel provisioner. Serving component
in-memory-channel.yaml Installs only the in-memory channel provisioner. Serving component, Eventing component
kafka.yaml Installs only the Kafka channel provisioner. Serving component, Eventing component
knative/eventing-sources
release.yaml† Installs the following sources: Kubernetes, GitHub, Container image, CronJob Serving component, Eventing component
release-gcppubsub.yaml Installs the following sources: PubSub Serving component, Eventing component
message-dumper.yaml Installs an Event logging service for debugging. Serving component, Eventing component

* See Installing logging, metrics, and traces for details about installing the various supported observability plug-ins.

† These are the recommended standard install files suitable for most use cases.

Installing Knative

Tip: From the table above, copy and paste the URL and filename into the commands below.

  1. To install Knative components or plugins, specify the filenames in the kubectl apply command:

    • To install an individual component or plgugin

      kubectl apply --filename [FILE_URL]

    • To install multiple components or plugins, append additional --filename [FILENAME] flags to the kubectl apply command:

      kubectl apply --filename [FILE_URL] --filename [FILE_URL] \
  --filename [FILE_URL]

      where [FILE_URL] is the URL path of the desired Knative release:

      https://github.com/knative/[COMPONENT]/releases/download/[VERSION]/[FILENAME].yaml

      [COMPONENT], [VERSION], and [FILENAME] are the Knative component, release version, and filename of the Knative component or plugin. Examples:

      • https://github.com/knative/serving/releases/download/v0.3.0/serving.yaml
      • https://github.com/knative/build/releases/download/v0.3.0/release.yaml
      • https://github.com/knative/eventing/releases/download/v0.3.0/release.yaml
      • https://github.com/knative/eventing-sources/releases/download/v0.3.0/release.yaml

    Example install commands:

    • To install the Knative Serving component with the set of observability plug-ins:

      kubectl apply --filename https://github.com/knative/serving/releases/download/v0.3.0/serving.yaml \
--filename https://github.com/knative/serving/releases/download/v0.3.0/monitoring.yaml

    • To install all three Knative components and the set of Eventing sources without an observability plugin:

      kubectl apply --filename https://github.com/knative/serving/releases/download/v0.3.0/serving.yaml \
--filename https://github.com/knative/build/releases/download/v0.3.0/release.yaml \
--filename https://github.com/knative/eventing/releases/download/v0.3.0/release.yaml \
--filename https://github.com/knative/eventing-sources/releases/download/v0.3.0/release.yaml

  2. Depending on what you chose to install, 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:

    kubectl get pods --namespace knative-serving
kubectl get pods --namespace knative-build
kubectl get pods --namespace knative-eventing
kubectl get pods --namespace knative-sources

    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.

  3. If you installed an observability plugin, run the following command to ensure that the necessary knative-monitoring pods show a STATUS of Running:

    kubectl get pods --namespace knative-monitoring

    See Installing logging, metrics, and traces for details about setting up the various supported observability plug-ins.

You are now ready to deploy an app, run a build, or start sending and receiving events in your Knative cluster.

What's next

Depending on the Knative components you installed, you can use the following guides to help you get started with Knative: