Installing Knative

This guide walks you through the installation of the latest version of Knative.

Knative has two components, which can be installed and used independently or together. To help you pick and choose the pieces that are right for you, here is a brief description of each:

  • Serving stable @ v0.9 provides an abstraction for stateless request-based scale-to-zero services.
  • Eventing alpha @ v0.2 provides abstractions to enable binding event sources (e.g. Github Webhooks, Kafka) and consumers (e.g. Kubernetes or Knative Services).

Knative also has an Observability plugin alpha @ v0.1 which provides standard tooling that can be used to get visibility into the health of the software running on Knative.

Before you begin

This guide assumes that you want to install an upstream Knative release on a Kubernetes cluster. A growing number of vendors have managed Knative offerings; see the Knative Offerings page for a full list.

Knative v0.13.0 requires a Kubernetes cluster v1.15 or newer, as well as a compatible kubectl. This guide assumes that you've already created a Kubernetes cluster, and that you are using bash in a Mac or Linux environment; some commands will need to be adjusted for use in a Windows environment.

Installing the Serving component

FEATURE STATE: stable @ Knative v0.9

The following commands install the Knative Serving component.

  1. Install the Custom Resource Definitions (aka CRDs):

    kubectl apply --filename https://github.com/knative/serving/releases/download/v0.13.0/serving-crds.yaml
    
  2. Install the core components of Serving (see below for optional extensions):

    kubectl apply --filename https://github.com/knative/serving/releases/download/v0.13.0/serving-core.yaml
    
  3. Pick a networking layer (alphabetical):

    FEATURE STATE: alpha @ Knative v0.8

    The following commands install Ambassador and enable its Knative integration.

    1. Create a namespace to install Ambassador in:

      kubectl create namespace ambassador
      
    2. Install Ambassador:

      kubectl apply --namespace ambassador \
        --filename https://getambassador.io/yaml/ambassador/ambassador-rbac.yaml \
        --filename https://getambassador.io/yaml/ambassador/ambassador-service.yaml
      
    3. Give Ambassador the required permissions:

      kubectl patch clusterrolebinding ambassador -p '{"subjects":[{"kind": "ServiceAccount", "name": "ambassador", "namespace": "ambassador"}]}'
      
    4. Enable Knative support in Ambassador:

      kubectl set env --namespace ambassador  deployments/ambassador AMBASSADOR_KNATIVE_SUPPORT=true
      
    5. To configure Knative Serving to use Ambassador by default:

      kubectl patch configmap/config-network \
        --namespace knative-serving \
        --type merge \
        --patch '{"data":{"ingress.class":"ambassador.ingress.networking.knative.dev"}}'
      
    6. Fetch the External IP or CNAME:

      kubectl --namespace ambassador get service ambassador
      

      Save this for configuring DNS below.

    FEATURE STATE: alpha @ Knative v0.12

    The following commands install Contour and enable its Knative integration.

    1. Install a properly configured Contour:

      kubectl apply --filename https://github.com/knative/net-contour/releases/download/v0.13.0/contour.yaml
      
    2. Install the Knative Contour controller:

      kubectl apply --filename https://github.com/knative/net-contour/releases/download/v0.13.0/net-contour.yaml
      
    3. To configure Knative Serving to use Contour by default:

      kubectl patch configmap/config-network \
        --namespace knative-serving \
        --type merge \
        --patch '{"data":{"ingress.class":"contour.ingress.networking.knative.dev"}}'
      
    4. Fetch the External IP or CNAME:

      kubectl --namespace contour-external get service envoy
      

      Save this for configuring DNS below.

    FEATURE STATE: alpha @ Knative v0.8

    For a detailed guide on Gloo integration, see Installing Gloo for Knative in the Gloo documentation.

    The following commands install Gloo and enable its Knative integration.

    1. Make sure glooctl is installed (version 1.3.x and higher recommended):

      glooctl version
      

      If it is not installed, you can install the latest version using:

      curl -sL https://run.solo.io/gloo/install | sh
      export PATH=$HOME/.gloo/bin:$PATH
      

      Or following the Gloo CLI install instructions.

    2. Install Gloo and the Knative integration:

      glooctl install knative --install-knative=false
      
    3. Fetch the External IP or CNAME:

      glooctl proxy url --name knative-external-proxy
      

      Save this for configuring DNS below.

    FEATURE STATE: stable @ Knative v0.9

    The following commands install Istio and enable its Knative integration.

    1. Installing Istio for Knative

    2. Install the Knative Istio controller:

      kubectl apply --filename https://github.com/knative/serving/releases/download/v0.13.0/serving-istio.yaml
      
    3. Fetch the External IP or CNAME:

      kubectl --namespace istio-system get service istio-ingressgateway
      

      Save this for configuring DNS below.

    FEATURE STATE: alpha @ Knative v0.12

    The following commands install Kourier and enable its Knative integration.

    1. Install the Knative Kourier controller:

      kubectl apply --filename https://raw.githubusercontent.com/knative/serving/v0.13.0/third_party/kourier-latest/kourier.yaml
      
    2. To configure Knative Serving to use Kourier by default:

      kubectl patch configmap/config-network \
        --namespace knative-serving \
        --type merge \
        --patch '{"data":{"ingress.class":"kourier.ingress.networking.knative.dev"}}'
      
    3. Fetch the External IP or CNAME:

      kubectl --namespace kourier-system get service kourier
      

      Save this for configuring DNS below.

  4. Configure DNS

    We ship a simple Kubernetes Job called “default domain” that will (see caveats) configure Knative Serving to use xip.io as the default DNS suffix.

    kubectl apply --filename https://github.com/knative/serving/releases/download/v0.13.0/serving-default-domain.yaml
    

    Caveat: This will only work if the cluster LoadBalancer service exposes an IPv4 address, so it will not work with IPv6 clusters, AWS, or local setups like Minikube. For these, see “Real DNS”.

    To configure DNS for Knative, take the External IP or CNAME from setting up networking, and configure it with your DNS provider as follows:

    • If the networking layer produced an External IP address, then configure a wildcard A record for the domain:

      # Here knative.example.com is the domain suffix for your cluster
      *.knative.example.com == A 35.233.41.212
      
    • If the networking layer produced a CNAME, then configure a CNAME record for the domain:

      # Here knative.example.com is the domain suffix for your cluster
      *.knative.example.com == CNAME a317a278525d111e89f272a164fd35fb-1510370581.eu-central-1.elb.amazonaws.com
      

    Once your DNS provider has been configured, direct Knative to use that domain:

    # Replace knative.example.com with your domain suffix
    kubectl patch configmap/config-domain \
      --namespace knative-serving \
      --type merge \
      --patch '{"data":{"knative.example.com":""}}'
    
  5. Monitor the Knative components until all of the components show a STATUS of Running or Completed:

    kubectl get pods --namespace knative-serving
    

At this point, you have a basic installation of Knative Serving!

Optional Serving extensions

FEATURE STATE: beta @ Knative v0.8

Knative also supports the use of the Kubernetes Horizontal Pod Autoscaler (HPA) for driving autoscaling decisions. The following command will install the components needed to support HPA-class autoscaling:

kubectl apply --filename https://github.com/knative/serving/releases/download/v0.13.0/serving-hpa.yaml
FEATURE STATE: alpha @ Knative v0.6

Knative supports automatically provisioning TLS certificates via cert-manager. The following commands will install the components needed to support the provisioning of TLS certificates via cert-manager.

  1. First, install cert-manager version 0.12.0 or higher

  2. Next, install the component that integrates Knative with cert-manager:

    kubectl apply --filename https://github.com/knative/serving/releases/download/v0.13.0/serving-cert-manager.yaml
    
  3. Now configure Knative to automatically configure TLS certificates.

FEATURE STATE: alpha @ Knative v0.12

If you plan to use cert-manager's support for provisioning wildcard certificates, then the most efficient way to provision certificates is with the namespace wildcard certificate controller. The following command will install the components needed to provision wildcard certificates in each namespace:

kubectl apply --filename https://github.com/knative/serving/releases/download/v0.13.0/serving-nscert.yaml

Getting started with Serving

Deploy your first app with the getting started with Knative app deployment guide. You can also find a number of samples for Knative Serving here.

Installing the Eventing component

FEATURE STATE: alpha @ Knative v0.2

The following commands install the Knative Eventing component.

  1. Install the Custom Resource Definitions (aka CRDs):

    kubectl apply --filename https://github.com/knative/eventing/releases/download/v0.13.0/eventing-crds.yaml
    
  2. Install the core components of Eventing (see below for optional extensions):

    kubectl apply --filename https://github.com/knative/eventing/releases/download/v0.13.0/eventing-core.yaml
    
  3. Install a default Channel (messaging) layer (alphabetical).

    1. First, Install Apache Kafka for Kubernetes

    2. Then install the Apache Kafka Channel:

      curl -L "https://github.com/knative/eventing-contrib/releases/download/v0.13.0/kafka-channel.yaml" \
       | sed 's/REPLACE_WITH_CLUSTER_URL/my-cluster-kafka-bootstrap.kafka:9092/' \
       | kubectl apply --filename -
      

    To learn more about the Apache Kafka channel, try our sample

    1. Install the Google Cloud Pub/Sub Channel:

      # This installs both the Channel and the GCP Sources.
      kubectl apply --filename https://github.com/google/knative-gcp/releases/download/v0.13.0/cloud-run-events.yaml
      

    To learn more about the Google Cloud Pub/Sub Channel, try our sample

    FEATURE STATE: alpha @ Knative v0.2

    The following command installs an implementation of Channel that runs in-memory. This implementation is nice because it is simple and standalone, but it is unsuitable for production use cases.

    kubectl apply --filename https://github.com/knative/eventing/releases/download/v0.13.0/in-memory-channel.yaml
    
    1. First, Install NATS Streaming for Kubernetes

    2. Then install the NATS Streaming Channel:

      kubectl apply --filename https://github.com/knative/eventing-contrib/releases/download/v0.13.0/natss-channel.yaml
      
  4. Install a default Broker (eventing) layer:

    FEATURE STATE: alpha @ Knative v0.5

    The following command installs an implementation of Broker that utilizes Channels:

    kubectl apply --filename https://github.com/knative/eventing/releases/download/v0.13.0/channel-broker.yaml
    

    To customize which channel implementation is used, update the following ConfigMap:

    apiVersion: v1
    kind: ConfigMap
    metadata:
      name: default-ch-webhook
      namespace: knative-eventing
    data:
      default-ch-config: |
        # This is the cluster-wide default channel.
        clusterDefault:
          apiVersion: messaging.knative.dev/v1alpha1
          kind: InMemoryChannel
    
        namespaceDefaults:
          # This allows you to specify different defaults per-namespace,
          # in this case the "some-namespace" namespace will use the Kafka
          # channel by default.
          some-namespace:
            apiVersion: messaging.knative.dev/v1alpha1
            kind: KafkaChannel
            spec:
              numPartitions: 2
              replicationFactor: 1
    
  5. Monitor the Knative components until all of the components show a STATUS of Running:

    kubectl get pods --namespace knative-eventing
    

At this point, you have a basic installation of Knative Eventing!

Optional Eventing extensions

FEATURE STATE: alpha @ Knative v0.5

The following command enables the default Broker on a namespace (here default):

kubectl label namespace default knative-eventing-injection=enabled
FEATURE STATE: alpha @ Knative v0.2

The following command installs the Github Source:

kubectl apply --filename https://github.com/knative/eventing-contrib/releases/download/v0.13.0/github.yaml

To learn more about the Github source, try our sample

FEATURE STATE: alpha @ Knative v0.5

The following command installs the Apache Camel-K Source:

kubectl apply --filename https://github.com/knative/eventing-contrib/releases/download/v0.13.0/camel.yaml

To learn more about the Apache Camel-K source, try our sample

FEATURE STATE: alpha @ Knative v0.5

The following command installs the Apache Kafka Source:

kubectl apply --filename https://github.com/knative/eventing-contrib/releases/download/v0.13.0/kafka-source.yaml

To learn more about the Apache Kafka source, try our sample

FEATURE STATE: alpha @ Knative v0.2

The following command installs the GCP Sources:

# This installs both the Sources and the Channel.
kubectl apply --filename https://github.com/google/knative-gcp/releases/download/v0.13.0/cloud-run-events.yaml

To learn more about the Cloud Pub/Sub source, try our sample.

To learn more about the Cloud Storage source, try our sample.

To learn more about the Cloud Scheduler source, try our sample.

To learn more about the Cloud Audit Logs source, try our sample.

Getting started with Eventing

You can find a number of samples for Knative Eventing here. A quick-start guide is available here.

Installing the Observability plugin

FEATURE STATE: alpha @ Knative v0.2

Install the following observability features to enable logging, metrics, and request tracing in your Serving and Eventing components.

All observibility plugins require that you first install the core:

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

After the core is installed, you can choose to install one or all of the following observability plugins:

  • Install Prometheus and Grafana for metrics:

    kubectl apply --filename https://github.com/knative/serving/releases/download/v0.13.0/monitoring-metrics-prometheus.yaml
    
  • Install the ELK stack (Elasticsearch, Logstash and Kibana) for logs:

    kubectl apply --filename https://github.com/knative/serving/releases/download/v0.13.0/monitoring-logs-elasticsearch.yaml
    
  • Install Jaeger for distributed tracing

    To install the in-memory (standalone) version of Jaeger, run the following command:

    kubectl apply --filename https://github.com/knative/serving/releases/download/v0.13.0/monitoring-tracing-jaeger-in-mem.yaml
    

    To install the ELK version of Jaeger (needs the ELK install above), run the following command:

    kubectl apply --filename https://github.com/knative/serving/releases/download/v0.13.0/monitoring-tracing-jaeger.yaml
    
  • Install Zipkin for distributed tracing

    To install the in-memory (standalone) version of Zipkin, run the following command:

    kubectl apply --filename https://github.com/knative/serving/releases/download/v0.13.0/monitoring-tracing-zipkin-in-mem.yaml
    

    To install the ELK version of Zipkin (needs the ELK install above), run the following command:

    kubectl apply --filename https://github.com/knative/serving/releases/download/v0.13.0/monitoring-tracing-zipkin.yaml