Skip to content

Latest commit

 

History

History
368 lines (292 loc) · 22.7 KB

Knative-custom-install.md

File metadata and controls

368 lines (292 loc) · 22.7 KB
title linkTitle weight type
Performing a Custom Knative Installation
Customizing your install
15
docs

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

If your cloud platform offers a managed Istio installation, we recommend installing Istio that way, unless you need the ability to customize your installation.

If you prefer to install Istio manually, if your cloud provider doesn't offer a managed Istio installation, or if you're installing Knative locally using Minkube or similar, see the Installing Istio for Knative guide.

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.

Note: If your install fails on the first attempt, try rerunning the commands. They will likely succeed on the second attempt. For background info and to track the upcoming solution to this problem, see issues #968 and #1036.

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-jaeger.yaml Installs only Jaeger* Serving component, ELK stack (monitoring-logs-elasticsearch.yaml), Jaeger Operator
monitoring-tracing-jaeger-in-mem.yaml Installs only Jaeger in-memory* Serving component, Jaeger Operator
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
build.yaml† Installs the Build component.
knative/eventing
release.yaml† Installs the Eventing component. Includes ContainerSource, CronJobSource, the in-memory channel provisioner.
eventing.yaml Installs the Eventing component. Includes ContainerSource and CronJobSource. Does not include the in-memory channel provisioner.
in-memory-channel.yaml Installs only the in-memory channel provisioner. Eventing component
kafka.yaml Installs only the Kafka channel provisioner. Eventing component
natss.yaml Installs only the NATSS channel provisioner. Eventing component
gcp-pubsub.yaml Installs only the GCP PubSub channel provisioner. Eventing component
knative/eventing-contrib
github.yaml† Installs the GitHub source. Eventing component
camel.yaml Installs the Apache Camel source. Eventing component
gcppubsub.yaml Installs the GCP PubSub source Eventing component
kafka.yaml Installs the Apache Kafka source. Eventing component
awssqs.yaml Installs the AWS SQS source. Eventing component
event-display.yaml Installs a Knative Service that logs events received for use in samples and debugging. Serving component, Eventing component

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

† 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. If you are upgrading from Knative 0.3.x: Update your domain and static IP address to be associated with the LoadBalancer istio-ingressgateway instead of knative-ingressgateway. Then run the following to clean up leftover resources:

    kubectl delete svc knative-ingressgateway -n istio-system
kubectl delete deploy knative-ingressgateway -n istio-system

    If you have the Knative Eventing Sources component installed, you will also need to delete the following resource before upgrading:

    kubectl delete statefulset/controller-manager -n knative-sources

    While the deletion of this resource during the upgrade process will not prevent modifications to Eventing Source resources, those changes will not be completed until the upgrade process finishes.

  2. To install Knative components or plugins, specify the filenames in the kubectl apply command. To prevent install failures due to race conditions, run the install command first with the -l knative.dev/crd-install=true flag, then a second time without the selector flag.

    1. Install only the CRDs by using the --selector knative.dev/crd-install=true flag:

      kubectl apply --selector knative.dev/crd-install=true \
--filename [FILE_URL] \
--filename [FILE_URL]

    2. Remove --selector knative.dev/crd-install=true and then run the command again to install the actual components or plugins:

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

      You can add as many --filename [FILE_URL] flags to your commands as needed.

      Syntax:

      • [FILE_URL]: URL path of a Knative component or plugin: https://github.com/knative/[COMPONENT]/releases/download/[VERSION]/[FILENAME].yaml

        • [COMPONENT]: A Knative component repository.
        • [VERSION]: Version number of a Knative component release.
        • [FILENAME]: Filename of the component or plugin that you want installed.

      [FILE_URL]Examples:

      • https://github.com/knative/serving/releases/download/v0.7.0/serving.yaml --selector networking.knative.dev/certificate-provider!=cert-manager
      • https://github.com/knative/build/releases/download/v0.7.0/build.yaml
      • https://github.com/knative/eventing/releases/download/v0.7.0/release.yaml
      • https://github.com/knative/serving/releases/download/v0.7.0/monitoring.yaml

      Note: By default, the Knative Serving component installation (serving.yaml) includes a controller for enabling automatic TLS certificate provisioning. If you do intend on immediately enabling auto certificates in Knative, you can remove the --selector networking.knative.dev/certificate-provider!=cert-manager statement to install the controller. Otherwise, you can choose to install the auto certificates feature and controller at a later time.

      Example install commands:

    • To install the Knative Serving component with the set of observability plugins but exclude the auto certificates controller, run the following commands:

      1. Installs the CRDs only:

        kubectl apply --selector knative.dev/crd-install=true \
  --filename https://github.com/knative/serving/releases/download/v0.7.0/serving.yaml --selector networking.knative.dev/certificate-provider!=cert-manager\
  --filename https://github.com/knative/serving/releases/download/v0.7.0/monitoring.yaml

      2. Remove the --selector knative.dev/crd-install=true flag and the run the command to install the Serving component and observability plugins:

        kubectl apply --filename https://github.com/knative/serving/releases/download/v0.7.0/serving.yaml --selector networking.knative.dev/certificate-provider!=cert-manager\
  --filename https://github.com/knative/serving/releases/download/v0.7.0/monitoring.yaml

    • To install all three Knative components and the set of Eventing sources without an observability plugin, run the following commands.

      In this example, the auto certificate controller is installed so that you can enable automatic certificates provisioning.

      1. Installs the CRDs only:

        kubectl apply --selector knative.dev/crd-install=true \
  --filename https://github.com/knative/serving/releases/download/v0.7.0/serving.yaml \
  --filename https://github.com/knative/build/releases/download/v0.7.0/build.yaml \
  --filename https://github.com/knative/eventing/releases/download/v0.7.0/release.yaml

      2. Remove the --selector knative.dev/crd-install=true flag and the run the command to install all the Knative components, including the Eventing sources and auto certificate controller:

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

  3. 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

    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.

  4. 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 plugins.

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:

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 4.0 License, and code samples are licensed under the Apache 2.0 License.