knative / docs

User documentation for Knative components.

_build
render list never never

(This guide only appears on GitHub, not the website, because it intentionally does not include YAML front-matter.)

Knative documentation

Welcome to the source file repository for our documentation on https://knative.dev.

Website

The Knative documentation website is built using Material for MkDocs.

View published documentation

View all Knative documentation and walk through our code samples on the website.

The Knative website includes versioned docs for recent releases, the Knative blog, links to all community resources, as well as Knative governance and contributor guidelines.

Run the website locally

For instructions, refer to Knative's docs contributor guide.

Website source files

Source files for the documentation on the website are located within the /docs directory of this repo.

Documentation versions for Knative releases

Each release of the Knative docs is available on the website (starting with 0.3) and their source files are all stored in branches of this repo.

Contributing to docs

We're excited that you're interested in contributing to the Knative documentation! Check out the resources below to get started.

If you are interested in contributing to Knative more broadly, please check out CLOTRIBUTOR for a list of all the help wanted issues in Knative.

Getting started

If you want to contribute a fix or add new content to the documentation, you can navigate through the /docs repo or use the Edit this page pencil icon on each of the pages of the website.

Before you can contribute, first start by reading the Knative contributor guidelines and learning about our community and requirements. In addition to reading about how to contribute to the docs, you should take a moment to learn about the Knative code of conduct, governance, values, and the various working groups and committees.

Knative community and contributor guidelines

Source files for all Knative community and governance topics are located separately in the knative/community repo.

To help you get started, see the following resources:

• Knative docs contributor's guide -- Contains information about how to contribute.

• New content templates:

  • Concept
  • Procedure
  • Troubleshooting
  • Blog

Getting help

• #knative-documentation on the CNCF Slack -- The #knative-documentation channel is the best place to go if you have questions about making changes to the documentation. We're happy to help!

• Documentation working group -- Come join us in the working group to meet other docs contributors and ask any questions you might have.

Help and support

Your help and feedback is always welcome!

If you find an issue please let us know, either by clicking the Create Issue on any of the website pages, or by directly opening an issue here in the repo.

If you have a question that you can't find an answer to, we would also like to hear about that. In addition to our docs, you can also reach out to the community for assistance. For example, ask a documentation-specific question on the #knative-documentation channel in Slack.

Also see the Knative community resource pages for a list of all the available community resources, including links to the various community discussion groups for both development as well as troubleshooting.

docs's Issues

Add a diagram for knative architecture

Otherwise anyone who installs it without seeing a diagram is going to get really scared and overwhelmed with:

$ kubectl apply -f https://storage.googleapis.com/knative-releases/latest/release.yaml
Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply
namespace/knative-build configured
Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply
clusterrole.rbac.authorization.k8s.io/knative-build-admin configured
Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply
serviceaccount/build-controller configured
Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply
clusterrolebinding.rbac.authorization.k8s.io/build-controller-admin configured
Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply
customresourcedefinition.apiextensions.k8s.io/builds.build.knative.dev configured
Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply
customresourcedefinition.apiextensions.k8s.io/buildtemplates.build.knative.dev configured
Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply
service/build-controller configured
Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply
service/build-webhook configured
Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply
configmap/config-logging configured
Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply
deployment.apps/build-controller configured
Warning: kubectl apply should be used on resource created by either kubectl create --save-config or kubectl apply
deployment.apps/build-webhook configured
namespace/knative-serving created
clusterrole.rbac.authorization.k8s.io/knative-serving-admin created
clusterrole.rbac.authorization.k8s.io/knative-serving-write created
serviceaccount/controller created
serviceaccount/autoscaler created
clusterrolebinding.rbac.authorization.k8s.io/knative-serving-controller-admin created
clusterrolebinding.rbac.authorization.k8s.io/knative-serving-autoscaler-write created
gateway.networking.istio.io/knative-shared-gateway created
service/knative-ingressgateway created
deployment.extensions/knative-ingressgateway created
horizontalpodautoscaler.autoscaling/knative-ingressgateway created
customresourcedefinition.apiextensions.k8s.io/configurations.serving.knative.dev created
customresourcedefinition.apiextensions.k8s.io/revisions.serving.knative.dev created
customresourcedefinition.apiextensions.k8s.io/routes.serving.knative.dev created
customresourcedefinition.apiextensions.k8s.io/services.serving.knative.dev created
service/activator-service created
service/controller created
service/webhook created
deployment.apps/activator created
configmap/config-autoscaler created
configmap/config-domain created
configmap/config-logging created
configmap/config-network created
configmap/config-observability created
deployment.apps/controller created
deployment.apps/webhook created
namespace/monitoring created
configmap/fluentd-ds-config created
configmap/scaling-config created
configmap/grafana-dashboard-definition-istio created
configmap/grafana-dashboard-definition-mixer created
configmap/grafana-dashboard-definition-pilot created
serviceaccount/fluentd-ds created
clusterrole.rbac.authorization.k8s.io/fluentd-ds created
clusterrolebinding.rbac.authorization.k8s.io/fluentd-ds created
daemonset.apps/fluentd-ds created
serviceaccount/kube-state-metrics created
role.rbac.authorization.k8s.io/kube-state-metrics-resizer created
rolebinding.rbac.authorization.k8s.io/kube-state-metrics created
clusterrole.rbac.authorization.k8s.io/kube-state-metrics created
clusterrolebinding.rbac.authorization.k8s.io/kube-state-metrics created
deployment.extensions/kube-state-metrics created
service/kube-state-metrics created
configmap/grafana-dashboard-definition-kubernetes-deployment created
configmap/grafana-dashboard-definition-kubernetes-capacity-planning created
configmap/grafana-dashboard-definition-kubernetes-cluster-health created
configmap/grafana-dashboard-definition-kubernetes-cluster-status created
configmap/grafana-dashboard-definition-kubernetes-control-plane-status created
configmap/grafana-dashboard-definition-kubernetes-resource-requests created
configmap/grafana-dashboard-definition-kubernetes-nodes created
configmap/grafana-dashboard-definition-kubernetes-pods created
configmap/grafana-dashboard-definition-kubernetes-statefulset created
serviceaccount/node-exporter created
clusterrole.rbac.authorization.k8s.io/node-exporter created
clusterrolebinding.rbac.authorization.k8s.io/node-exporter created
daemonset.extensions/node-exporter created
service/node-exporter created
service/elasticsearch-logging created
serviceaccount/elasticsearch-logging created
clusterrole.rbac.authorization.k8s.io/elasticsearch-logging created
clusterrolebinding.rbac.authorization.k8s.io/elasticsearch-logging created
statefulset.apps/elasticsearch-logging created
deployment.apps/kibana-logging created
service/kibana-logging created
service/fluentd-ds created
configmap/grafana-dashboard-definition-knative-efficiency created
configmap/grafana-dashboard-definition-knative created
configmap/grafana-datasources created
configmap/grafana-dashboards created
service/grafana created
deployment.apps/grafana created
logentry.config.istio.io/requestlog created
fluentd.config.istio.io/requestloghandler created
rule.config.istio.io/requestlogtofluentd created
metric.config.istio.io/revisionrequestcount created
metric.config.istio.io/revisionrequestduration created
metric.config.istio.io/revisionrequestsize created
metric.config.istio.io/revisionresponsesize created
prometheus.config.istio.io/revisionpromhandler created
rule.config.istio.io/revisionpromhttp created
service/zipkin created
deployment.extensions/zipkin created
service/kube-controller-manager created
service/prometheus-system-discovery created
configmap/prometheus-scrape-config created
serviceaccount/prometheus-system created
role.rbac.authorization.k8s.io/prometheus-system created
role.rbac.authorization.k8s.io/prometheus-system created
role.rbac.authorization.k8s.io/prometheus-system created
role.rbac.authorization.k8s.io/prometheus-system created
clusterrole.rbac.authorization.k8s.io/prometheus-system created
rolebinding.rbac.authorization.k8s.io/prometheus-system created
rolebinding.rbac.authorization.k8s.io/prometheus-system created
rolebinding.rbac.authorization.k8s.io/prometheus-system created
rolebinding.rbac.authorization.k8s.io/prometheus-system created
clusterrolebinding.rbac.authorization.k8s.io/prometheus-system created
service/prometheus-system-np created
statefulset.apps/prometheus-system created
logentry.config.istio.io/requestlog unchanged
fluentd.config.istio.io/requestloghandler unchanged
rule.config.istio.io/requestlogtofluentd unchanged
metric.config.istio.io/revisionrequestcount unchanged
metric.config.istio.io/revisionrequestduration unchanged
metric.config.istio.io/revisionrequestsize unchanged
metric.config.istio.io/revisionresponsesize unchanged
prometheus.config.istio.io/revisionpromhandler unchanged
rule.config.istio.io/revisionpromhttp unchanged

Make sure the community stuff is up-to-date and accurate

Hello-world sample in Python

Write sample app doc based on Node.js example

Document how to assign a domain name to your services

Need to document how to map your running services to a FQDN. There is an open issue about the internal (cluster) DNS name vs. the public DNS name that we still need to resolve.

Build: End-to-end Instructions for git repo to container using a build-template

"Setting up a Custom Domain" example differs from what I got after a fresh install

apiVersion: v1
data:
  # These are example settings of domain.
  # example.org will be used for routes having app=prod.
  example.org: |
    selector:
      app: prod

  # Default value for domain, for routes that does not have app=prod labels.
  # Although it will match all routes, it is the least-specific rule so it
  # will only be used if no other domain matches.
  example.com: ""
kind: ConfigMap
[...]

is not what I got, I got:

apiVersion: v1
data:
  example.com: ""
kind: ConfigMap
[...]

Document how to enable TLS for your service

Add what's not working section

Add some documentation about what we know is not working, but which we intend to address in the future. (I.e. "known gaps")

Some examples:

• SSL configuration
• SSL provisioning
• DNS integration

Add post install cluster config how-to (hostname, network scope for Istio inject, DNS config, TLS etc.)

Serving readme: what is serving?

Two issues in Knative-with-Minikube.md

Expected Behavior

All steps in the document work to install Knative on minikube

Actual Behavior

There are two mistakes in the document:

In the Knative section there is a reference in the text to https://storage.googleapis.com/elafros-releases/latest/release-lite.yaml which doesn't exist. The kubectl apply -f command uses the correct URL to the YAML file.

The command to wait for Knative resources to be ready uses the wrong namespace. The document currently says to execute kubectl get pods -n knative-serving-system --watch, but the correct command is kubectl get pods -n knative-serving --watch. When using the wrong namespace, the command returns nothing, since the knative-serving-system namespace does not exist.

Steps to Reproduce the Problem

1. Follow the steps in the document
2. When you run the kubectl get pods -n knative-serving-system --watch command, there will be no output

Additional Info

Add a common license footer for docs

Confirmed with counsel, and we have a recommended way of communicate the license on docs, including docs which contain inline code samples. In addition to the top-level LICENSE file in the repository containing the text of the Apache License 2.0 (already done), we should add the following footer to each doc:

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.

In Markdown, just copy the following text verbatim:

Except as otherwise noted, the content of this page is licensed under the
[Creative Commons Attribution 4.0 License](https://creativecommons.org/licenses/by/4.0/),
and code samples are licensed under the
[Apache 2.0 License](https://www.apache.org/licenses/LICENSE-2.0).

Need end to end testing for samples in knative/docs.

(adrcunha) Once knative/serving#1291 is closed we can create a Prow presubmit job to run all the samples, just like the integration tests in the other repos.

Create build tests

"build tests" in this context is not restricted to code, might even include checking markdown file formatting.

Create repo readme page

... to highlight the repo structure, main content elements (how-tos vs samples) and best places to start for each

There is no document on how to use node ip and node port in minikube or baremetal environment

Expected Behavior

There should be instructions how to use node ip and node port when no external load balancer is used.

Actual Behavior

There is no document on how to use node ip and node port in minikube or baremetal environment

Steps to Reproduce the Problem

Additional Info

/assign @rootfs

Build: Need a readme in docs/build.

Add a Knative logo

Update the org and repos with the Knative logo once available.

Hello-world sample in C#

Write sample app doc based on Node.js example

Hello-world sample in Ruby

Write sample app doc based on Node.js example

google-prow-robot does not have sufficient permissions in this repository.

The Prow robot cannot modify labels in this repository.

error adding label to knative/docs PR #17: status code 403 not one of [200], body: {
"message":"Must have admin rights to Repository.",
"documentation_url":"https://developer.github.com/v3/issues/labels/#add-labels-to-an-issue"}

Since the bot has appropriate permissions in other repos in this org, this suggests that the bot permissions are being configured individually for each repo in the knative org instead of being set org wide.
Please give the bot 'admin' permissions to the org so that it has the permissions it needs on all repos including newly created ones.

@adrcunha

Replace demo-domain.com with example.com

Expected Behavior

Docs match the default domain in Knative

Actual Behavior

Docs match the previous default domain in Knative

Sort out the license agreement on docs + samples

Are these licensed under Google CLA, Creative Commons, or something else. Dewitt to sort out with legal.

Pull end user docs from knative/serving into this repo

Hello-world sample in Node.js

Write sample app doc based on Node.js example

GKE install step seems duplicated

https://github.com/knative/docs/blob/master/install/Knative-with-GKE.md

The guide starts with "Knative requires a Kubernetes cluster v1.10 or newer. If you don't have one, you can create one on Google Cloud Platform."

So I assumed I had to create one at this step.
I did not understand that the guide later tells me how to do so: https://github.com/knative/docs/blob/master/install/Knative-with-GKE.md#creating-a-kubernetes-cluster

I'll send a PR with a suggestion

Document scenarios for config maps

Document the config maps (#39) and the scenarios which apply to the config maps.

Rename `helloworld-*` samples to `hellogcp-$1`

Expected Behavior

helloworld should work in any Knative environment.

Actual Behavior

helloworld requires gcloud and a GCP account.

Steps to Reproduce the Problem

1. attempt to deploy any of the sample-* applications without a GCP account

Additional Info

It's good to have samples that use GCP, but they should be labeled as such and not presented as a generic helloworld sample.

Need to highlight the key scenarios that are working now in each repo

For example:

• Build
  • End to end container build
• Serving
  • Deploy from container
  • Traffic splitting (blue/green testing)
• Events
  • PubSub topic subscription

Are there any others that are high priority and ready to include for the launch?

Private repo sample uses invalid branch property in build git source spec

git source specification currently supports url and revision attributes (see here).
private repo sample is broken as it references unsupported branch property (see here).

Please have the example updated and working.

Route traffic splitting demo

Using https://github.com/knative/docs/serving/samples/blue-green-deployment.md

Blue/green deployment guide

Create unit tests

"unit tests" in this context is not restricted to code, might even include linting markdown files.

Autoscale, knative-routing, and telemetry sample refers to missing Dockerfile

Expected Behavior

This step would work https://github.com/knative/docs/blob/master/serving/samples/autoscale-go/README.md#setup.

Actual Behavior

Looks like the Dockerfile was dropped during the repo move.

Steps to Reproduce the Problem

Try https://github.com/knative/docs/blob/master/serving/samples/autoscale-go/README.md, at the Setup step (https://github.com/knative/docs/blob/master/serving/samples/autoscale-go/README.md#setup)

Additional Info

Setup Prow for knative/docs

We have to:

• Create test infra
• Setup prow

Something without 8 Gi

We need to be able to do something basic with one component of knative without needing 8 Gi to run minikube.

As crazy as it sounds to some, a lot of people do not have 8 Gi to spare on their machine.

Tech writing review of API specs for clarity

Expected Behavior

API specs are reviewed and tested

/assign @RichieEscarez

Publish runtime contract

Need Knative configuration instructions

Expected Behavior

When I want to make configuration for some new code or behavior, I need guidance on where to put it.

Additional Info

There are several places to put configuration currency:

Various config maps (scaling, observability, domain/routing)
binary flags in code + controller flags

We need guidance about which one to use, and why.

Pin the docs repository once the repository is public

Github repositories can be "pinned" to show in the main UI by default. Unfortunately this can't be done until the repos are public, but as soon as they are, the docs repo should be pinned to the top.

Waiting forever for ingress

In this section of the "Knative the easy way (with Minikube)" doc, there are the following instructions:

Wait for the ingress to get created. This may take a few seconds. You can check by running:

kubectl get ing --watch

In fact, even after an hour, no Ingress resource exists anywhere in the entire cluster.

It goes without saying that subsequent steps that involve that resource, such as this one, also fail:

export SERVICE_HOST=`kubectl get ing primer-ingress \
 -o jsonpath="{.spec.rules[0]['host']}"`

fwiw, this broke within the last week or so.

Hello-world sample in PHP

Write sample app doc based on Node.js example

Hello-world sample in Java

Write sample app doc based on Node.js example

Cannot deploy container image from Google Cloud Container Registry

I followed the Knative on GKE installation steps: https://github.com/knative/docs/blob/master/install/Knative-with-GKE.md

I then built a container image and put it in Google Container Registry, in the same project as my cluster.

If I make public the GCS bucket that hosts my container images, then I can successfully deploy.

Name:         rendertest
Namespace:    default
Labels:       <none>
Annotations:  kubectl.kubernetes.io/last-applied-configuration={"apiVersion":"serving.knative.dev/v1alpha1","kind":"Service","metadata":{"annotations":{},"name":"rendertest","namespace":"def
ault"},"spec":{"runLates...
API Version:  serving.knative.dev/v1alpha1
Kind:         Service
Metadata:
  Cluster Name:
  Creation Timestamp:  2018-07-13T22:14:46Z
  Generation:          1
  Resource Version:    420159
  Self Link:           /apis/serving.knative.dev/v1alpha1/namespaces/default/services/rendertest
  UID:                 26851c1c-86ea-11e8-96fc-42010a8a0010
Spec:
  Generation:  1
  Run Latest:
    Configuration:
      Revision Template:
        Metadata:
          Creation Timestamp:  <nil>
        Spec:
          Concurrency Model:  Multi
          Container:
            Env:
              Name:   TARGET
              Value:  Go Sample v1
            Image:    gcr.io/demo-project/render
            Name:
            Resources:
Status:
  Conditions:
    Last Transition Time:        2018-07-13T22:14:55Z
    Message:                     Revision "rendertest-00001" failed with message: "DENIED: \"Permission denied for \\\"latest\\\" from request \\\"/v2/demo-project/render/manifests/late
st\\\". \"".
    Reason:                      RevisionFailed
    Status:                      False
    Type:                        ConfigurationsReady
    Last Transition Time:        2018-07-13T22:15:16Z
    Message:                     Latest Revision of Configuration "rendertest" is deleted.
    Reason:                      RevisionMissing
    Status:                      False
    Type:                        RoutesReady
    Last Transition Time:        2018-07-13T22:29:27Z
    Message:                     Latest Revision of Configuration "rendertest" is deleted.
    Reason:                      RevisionMissing
    Status:                      False
    Type:                        Ready
  Domain:                        rendertest.default.live-demo.net
  Latest Created Revision Name:  rendertest-00001
  Observed Generation:           1
Events:                          <none>

Not sure what "on day 2" means

https://github.com/knative/docs/blob/master/README.md
"Updating your application on day 2 without an outage"

What about "Updating your application without downtime"?

Install docs should be reviewed and tested

Expected Behavior

Install instructions are clear and the install works

Actual Behavior

During the last hackathon everyone had difficulties with the install.

/assign @samodell

Clean up the code samples that aren't helloworld.

Here's the samples and who's working on them:

Samples

• autoscale-go @josephburnett
• build-privat-repo-go @samodell PR is #213
• buildpack-app-dotnet @samodell PR is #222
• buildpack-function-nodejs @samodell #222
• gitwebhook-go rgregg PR is #215
• grpc-ping-go @averikitsch
• knative-routing-go
• rest-api-go @averikitsch PR is #225
• source-to-url-go
• telemetry-go
• thumbnailer-go @samodell PR is #231

Hello-world sample in Go

Write sample app doc based on Node.js example

All the docs should be in this repo (not just "end user docs")

Expected Behavior

Have a single place to go to see all the documentation for Knative projects.

Actual Behavior

Documentation is split across many different repos today.

Samples: README files duplicate the sample files

Most of the README of our samples are duplicating the sample files by embedding source code.

This requires us to keep them in sync, which is error prone if nothing is here to enforce it.

I instead recommend to not copy the sample content inside the README files, and only link to the files.

Add issue and PR templates to this repo