diff --git a/.gitignore b/.gitignore index af56f6105..da9723e71 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1,3 @@ .DS_Store .idea/ + diff --git a/README.md b/README.md new file mode 100644 index 000000000..f8a164f0b --- /dev/null +++ b/README.md @@ -0,0 +1,14 @@ +# Welcome to the source file repository for Knative documentation + +## View published docs + +Use the [Knative Documentation website](http://www.knative.dev/docs) to view the +docs and learn about Knative. + +## Source files + +View the source files if you want to contribute a fix or add new content. +Each release of the Knative docs are +[branched](https://github.com/knative/docs/branches). If you are looking for an +archived doc set, see the list of available versions in +[Knative doc releases](./doc-releases.md). diff --git a/_index.html b/_index.html new file mode 100644 index 000000000..2e5cfc768 --- /dev/null +++ b/_index.html @@ -0,0 +1,129 @@ ++++ +title = "Knative" + ++++ + +{{< blocks/cover title="Welcome to the Knative Project!" image_anchor="top" height="max" color="dark" >}} +
+ }}"> + Learn More + + + View Repository + +

Kubernetes-based platform to build, deploy, and manage modern serverless workloads.

+
+ {{< blocks/link-down color="info" >}} +
+
+{{< /blocks/cover >}} + + +{{% blocks/lead color="primary" %}} +Knative provides a set of middleware components that are essential to build modern, source-centric, and container-based applications that can run anywhere: on premises, in the cloud, or even in a third-party data center. + +{{% /blocks/lead %}} + + +{{% blocks/section %}} +
+

Essential base primitives for all

+Knative components are built on Kubernetes and codify the best practices shared by successful real-world Kubernetes-based frameworks. It enables developers to focus just on writing interesting code, without worrying about the “boring but difficult” parts of building, deploying, and managing an application. +
+{{% /blocks/section %}} + +{{% blocks/section %}} +
+

+Developer-friendly software

+Knative offers a set of reusable components that focuses on solving many mundane but difficult tasks such as orchestrating source-to-container workflows, routing and managing traffic during deployment, auto-scaling your workloads, or binding running services to eventing ecosystems. Developers can even use familiar idioms, languages, and frameworks to deploy any workload: functions, applications, or containers. +
+{{% /blocks/section %}} + +{{% blocks/section %}} +
+

Supports popular development patterns

+Knative focuses on an idiomatic developer experience. It supports common development patterns such as GitOps, DockerOps, ManualOps, as well as tools and frameworks such as Django, Ruby on Rails, Spring, and many more. +
+{{% /blocks/section %}} + +{{% blocks/section %}} +
+

Best of both worlds: Flexibility and control

+Knative is designed to plug easily into existing build and CI/CD toolchains. By focusing on open-source-first technologies that run anywhere, on any cloud, on any infrastructure supported by Kubernetes, enterprises are free to move their workloads wherever they run best. This offers the flexibility and control customers need to adapt the system to their own unique requirements. +
+{{% /blocks/section %}} + +{{% blocks/section %}} +
+

Operator-friendly

+Knative is designed to be run as a service by all major cloud providers. Google currently works with industry leaders such as Pivotal, SAP, Red Hat, IBM, and many others to create the building blocks that will best suit the needs of developers. Knative powers real-world workloads and is also compatible with other cutting-edge technologies such as Kubernetes and Istio. +
+{{% /blocks/section %}} + + + +{{< blocks/section >}} + +

Knative Features

+ + + + + + + + + + + + + + + + + + + + + + +
Feature NameFeature Description
ServingScale to zero, request-driven compute model
BuildCloud-native source to container orchestration
EventingUniversal subscription, delivery, and management of events
+ +{{< /blocks/section >}} + + +{{< blocks/section color="light" >}} + +{{% blocks/feature icon="fab fa-slack" title="Talk to us on Slack!" url="https://knative.slack.com/" %}} +Interested in learning more, speaking to other contributors, or finding answers? +{{% /blocks/feature %}} + + +{{% blocks/feature icon="fab fa-github" title="Contributions welcome!" url="./contributing/" %}} +Want to join the fun? New users are always welcome! +{{% /blocks/feature %}} + + +{{% blocks/feature icon="fab fa-twitter" title="Follow us on Twitter!" url="https://twitter.com/KnativeProject" %}} +For announcement of latest features etc. +{{% /blocks/feature %}} + + +{{< /blocks/section >}} + + + + diff --git a/background.png b/background.png new file mode 100644 index 000000000..9875583a2 Binary files /dev/null and b/background.png differ diff --git a/blog/_index.md b/blog/_index.md new file mode 100644 index 000000000..dda673597 --- /dev/null +++ b/blog/_index.md @@ -0,0 +1,12 @@ +--- +title: "Knative blog" +linkTitle: "Blog" +menu: + main: + weight: 30 +--- + + +Welcome to the Knative **blog** section. Keep up-to-date with product and +release announcements, read articles, hear about recent social events, and +find out where the Knative team will be talking next. diff --git a/blog/articles/Build--deploy--manage-modern-serverless-workloads-using-Knative-on-Kubernetes.html b/blog/articles/Build--deploy--manage-modern-serverless-workloads-using-Knative-on-Kubernetes.html new file mode 100644 index 000000000..c87d70c8f --- /dev/null +++ b/blog/articles/Build--deploy--manage-modern-serverless-workloads-using-Knative-on-Kubernetes.html @@ -0,0 +1,18 @@ +--- +title: "Build, deploy, manage modern serverless workloads using Knative on Kubernetes" +linkTitle: "Serverless workloads using Knative" +date: 2018-11-14 +description: "Learn how to build, deploy, and manage modern serverless workloads using Knative on Kubernetes." +--- + +
+
+By now, Kubernetes should be the default target for your deployments. Yes, there are still use-cases where Kubernetes is not the optimal… +
+
+By now, Kubernetes should be the default target for your deployments. Yes, there are still use-cases where Kubernetes is not the optimal… +
+
+

Build, deploy, manage modern serverless workloads using Knative on Kubernetes

By now, Kubernetes should be the default target for your deployments. Yes, there are still use-cases where Kubernetes is not the optimal choice, but these represent an increasingly smaller number of modern workloads.

The main value of Kubernetes is that it greatly abstracts much of the infrastructure management pain. The broad support amongst virtually all major Cloud Service Providers (CSP) also means that your workloads are portable. Combined with the already vibrant ecosystem of Kubernetes-related tools, means that the experience of the operator, the person responsible for managing Kubernetes, is now pretty smooth.

But what about the experience of the developer, the person who builds solutions on top of Kubernetes?

Despite what some might tell you, Kubernetes is not yet today’s application server. For starters, the act of developing, deploying and managing services on Kubernetes is still too complicated. Yes, there are many open source projects for logging, monitoring, integration, etc., but, even if you put these together just right, the experience of developing on Kubernetes is still fragile and way too labour-intensive.

As if that wasn’t enough, the growing popularity of functions as the atomic unit of code development further contributes to the overall complexity. Often creating different development patterns on two disconnected surface areas:one for functions (FaaS) and one for applications (PaaS).

As the result, developers today are being forced to worry about infrastructure-related concerns: such as, image building, registry publishing, deployment services, load balancing, logging, monitoring, and scaling. However, what all they really want to do is write code.

Introducing Knative

At Google Cloud Next in San Francisco this week, Google announced an early preview of the GKE serverless add-on (g.co/serverlessaddon). Google also open-sourced Knative (kay-nay-tiv), the project that powers the serverless add-on (github.com/knative).

Knative implements many of the learnings from Google. The open source project already has contributions from companies like Pivotal, IBM, Red Hat and SAP and collaboration with open-source Function-as-a-Service framework communities like OpenWhisk, riff, and Kyma who either replatform on to Knative or consume one or more components from the Knative project.

Knative audience
Knative helps developers build, deploy, and manage modern serverless workloads on Kubernetes.

It provides a set of building blocks that enable modern, source-centric and container-based development workloads on Kubernetes:

  • Build — Source-to-container build orchestration
  • Eventing — Management and delivery of events
  • Serving — Request-driven compute that can scale to zero

Knative documentation provides instructions on how to install it on hosted Kubernetes offering like Google Cloud Platform or IBM, and on-prem Kubernetes installations, like the one offered by Pivotal. Finally, Knative repository also includes samples and how-to instructions to get you started developing on Kubernetes.

Knative Overview

Knative is based on the premise of clear separation of concerns. It allows developers and operators to reason about the workload development, deployment, and management by defining primitive objects in a form of Custom Resource Definitions (CRDs) which extend on the object model found in Kubernetes.

Knative defines primitives with clear separation of concerns
  • Configuration — is the desired state for your service, both code and configuration
  • Revision — represents an immutable point-in-time snapshot of your code and configuration
  • Route — assigns traffic to a revision or revisions of your service
  • Service — is the combined lite version of all the above objects to enable simple use cases

In addition to these objects, Knative also defines principle objects for eventing… you know, because serverless. Knative decouples event producers and consumers and implements CNCF CloudEvents (v0.1) to streamline event processing.

Knative eventing constructs
  • Event Sources — represents the producer of events (e.g. GitHub)
  • Event Types — describes the types of events supported by the different event sources (e.g. Webhook for the above mentioned GitHub source)
  • Event Consumers — represents the target of your action (i.e. any route defined by Knative)
  • Event Feeds — is the binding or configuration connecting the event types to actions

The functional implementation of the Knative object model means that Knative is both easy to start with, but capable enough to address more advanced use cases as the complexity of your solutions increases.

Summary

I hope this introduction gave you an understanding of the value of Knative. And how the Knative objects streamline development on Kubernetes, regardless if you work on applications or functions.

Over the next few weeks I will be covering each one of the key Knative usage patterns (image push, blue/green deployment model, source to URL, etc). In each post, I will also provide a sample code to illustrate that pattern and allow you to reproduce them on Knative. I’m super excited to share Knative with you, and I hope you come back to find out more.

+
+
diff --git a/blog/articles/_index.md b/blog/articles/_index.md new file mode 100644 index 000000000..291488d44 --- /dev/null +++ b/blog/articles/_index.md @@ -0,0 +1,6 @@ +--- +title: "Knative articles" +linkTitle: "Articles" +weight: 30 +--- + diff --git a/blog/events/Knative-at-KubeCon-Seattle.html b/blog/events/Knative-at-KubeCon-Seattle.html new file mode 100644 index 000000000..323b008a4 --- /dev/null +++ b/blog/events/Knative-at-KubeCon-Seattle.html @@ -0,0 +1,15 @@ +--- +title: "Knative at KubeCon Seattle" +linkTitle: "KubeCon 2018" +date: 2018-12-04 +description: "Knative sessions at KubeCon" +--- + +
+
+As we approach KubeCon and CloudNativeCon in Seattle (Dec. 11–13), we wanted to share the different Knative-related sessions that will be… +
+
+

Knative at KubeCon Seattle

Update (2018–12–19): Added sessions/keynotes/interviews links to videos

KubeCon SEA 2018

As we approach KubeCon and CloudNativeCon in Seattle (Dec. 11–13), we wanted to share the different Knative-related sessions that will be offered next week.

We are proud of the project’s progress so far. The number of sessions, variety of topics, and number of different companies represented by the speakers, truly represent the breadth of the growing community behind Knative.

Monday, Dec 10

Tuesday, Dec 11

Wednesday, Dec 12

Thursday, Dec 13

Looking forward to seeing you in Seattle next week. Remember, if you can’t attend, there will be a live video broadcast from the keynotes, and the break-out sessions should also be available shortly after the conference.

+
+
diff --git a/blog/events/_index.md b/blog/events/_index.md new file mode 100644 index 000000000..00aa8859a --- /dev/null +++ b/blog/events/_index.md @@ -0,0 +1,5 @@ +--- +title: "Knative social events" +linkTitle: "Events" +weight: 20 +--- diff --git a/blog/releases/Announcing-Knative-v0-2-Release.html b/blog/releases/Announcing-Knative-v0-2-Release.html new file mode 100644 index 000000000..7cf2255d1 --- /dev/null +++ b/blog/releases/Announcing-Knative-v0-2-Release.html @@ -0,0 +1,15 @@ +--- +title: "Announcing the Knative v0.2 release" +linkTitle: "Version 0.2 release" +date: 2018-11-14 +description: "The Knative v0.2 release announcement" +--- + +
+
+Improved pluggability, autoscaling, stability, and performance +
+
+

Announcing Knative v0.2 Release

Improved pluggability, autoscaling, stability, and performance

We are excited to announce a new release of Knative, the set of middleware components for building modern applications on Kubernetes. The 0.2 release of Knative is the first significant update since the project’s launch in July. It represents months of hard work by the entire Knative community to address our learnings from the growing number of Knative deployments.

The most exciting aspect of the 0.2 release is the inclusion of eventing. The Eventing component complements the other two foundational blocks already defined by Knative: Serving and Build. We look forward to the new types of events and innovative solutions the community will develop using this new capability.

Serving made significant improvements “under the hood,” encapsulating key areas of Knative into subsystems with new internal APIs to enable support for pluggable networking, autoscaling, and caching.

The complete release notes are available in Knative Serving, Build, and Eventing repositories. Here are a few highlights:

New Eventing Resource Model 
The eventing repo went through a significant rework of the resource model, resulting in migration of sources into Custom Resource Definitions (CRDs). Now, eventing includes a sophisticated use of standard Kubernetes concepts, resulting in better validation, cleaner interfaces, and RBAC support. The new architecture uses a simpler object model that is centered around channels and subscriptions.

Looser Coupling
One of the pieces of positive feedback we received on v0.1 was the “tasteful” choices defining Knative building blocks. In v0.2, Knative leans into this even further to enable operators to install the Build, Serving, and Eventing components independent of one another. The contract that enables these loose couplings between Knative components will also enable third party integrations over time, such as using a non-Knative Build with Serving, or delivering events to non-Serving deployments. We are excited to see what direction the community takes this.

Pluggable Subsystems
We also got a lot of feedback about wanting to customize Knative. The goal was always to support some measure of pluggability, so customization was significantly improved in v0.2. We introduced 3 new internal APIs in v0.2 to separate our core resource model from the subsystems that implement them: Networking, Autoscaling, and Caching. Networking enables developers to replace our Istio dependency with alternative ingress implementations. Autoscaling enables developers to replace our “cheap and cheerful” autoscaler with one of their own designs. Caching enables developers to employ image caching strategies to preload container images across their cluster (no implementation bundled, so this is a pure extension-point).

Improved Cold-Starts
Two of the dominant factors in cold-start performance are side-car injection and image pull latency. With their 1.0.2 release, Istio has made progress on reducing the Envoy programming time. In addition, we’ve made it possible to install Knative with side-car injection disabled. To enable folks to combat image pull latency, we have exposed a new extension point called an “Image” resource (part of knative/caching), which contains all the information needed for a controller to pre-load user images across a cluster. Caching is another feature we are excited to see the community build upon.

Autoscaling
We have replaced the previous per-Revision autoscalers with a single shared autoscaler. The new autoscaler is based on the same logic as the previous autoscaler, but has evolved to be purely metrics driven (including 0->1->0), eliminating the unnecessary Revision servingState field. We have replaced ConcurrencyModel (Single or Multi) with an integer ContainerConcurrency field. This allows limiting concurrency to values other than 1 for certain use cases (for example, limited thread pools).

Build
Knative Build added many incremental improvements, including the new ClusterBuildTemplate resource. Operators are now able to install a set of BuildTemplates one time instead of once per-Namespace. Build template parameters can now also apply to build step image names. New features of the Build spec allow users to specify a build-wide timeout, node selectors, and affinity. Last but not least, build status has been extended to report per-step build progress and build pending times.

Knative at KubeCon

Come and talk to us! There are a number of Knative sessions at the upcoming KubeCon conferences, both in Shanghai and Seattle.

Shanghai

Seattle

+
+
diff --git a/blog/releases/Announcing-Knative-v0-3-Release.html b/blog/releases/Announcing-Knative-v0-3-Release.html new file mode 100644 index 000000000..bf7ba3991 --- /dev/null +++ b/blog/releases/Announcing-Knative-v0-3-Release.html @@ -0,0 +1,15 @@ +--- +title: "Announcing the Knative v0.3 release" +linkTitle: "Version 0.3 release" +date: 2019-01-15 +description: "The Knative v0.3 release announcement" +--- + +
+
+Knative’s momentum continues! Once again, we are excited to announce a new release of Knative. After a series of architectural changes… +
+
+

Announcing Knative v0.3 Release

Knative’s momentum continues! Once again, we are excited to announce a new release of Knative. After a series of architectural changes announced in the previous release, v0.3 implements many of the learnings from the growing number of Knative deployments, increases operational control, and improves stability.

As we move to a more predictable release schedule based on six week cadence, Knative releases will now be smaller and more frequent. We did this to enable a tighter feedback loop with our users and allow for smoother course corrections as we continue to learn from our growing number of users.

Starting with the v0.3 release, Knative now requires Kubernetes 1.11, due to the use of `/status` sub-resource support, which went Beta in Kubernetes 1.11 and fixes a long-standing Kubernetes CRD bug.

The complete set of Knative v0.3 release notes outlining the new features as well as bug fixes and architectural changes are available in the Serving, Build, and Eventing repositories. Here are a few highlights:

Serving API

With the v0.3 release, Knative now exposes a few additional parameters in its API. These include explicit Revision timeouts and the ability to specify the port for incoming traffic to the user container, which Knative previously exposed to the container using the “$PORT” environment variable.

An even bigger addition is support for the Kubernetes resources spec, which allows you to specify reservations and limits on the user container. Besides allowing the service to specify how much CPU and memory (RAM) it needs or limit how much it can use; this also allows developers to request access to hardware accelerators like GPU if their cluster includes nodes configured with that capability.

In v0.3, Knative is also more proactive about rolling out operator changes. Changes to serving ConfigMaps are now immediately reconciled and rolled out.

Autoscaling

Building on the new single shared autoscaler introduced in the previous release, v0.3 introduces a more aggressive scale-to-zero strategy, which will by default scale Revisions down to zero pods after only 30 seconds of inactivity. The default Knative Pod Autoscaler (KPA) now supports revision-level concurrency targets.

As shown in our Kubecon demo, Knative now offers Horizontal Pod Autoscaler (HPA). This is useful for those who need to opt-out of KPA and use CPU instead of request rate as a scaling metric. (Note: HPA-class Revisions will not scale to zero).

Lastly, you can now also mutate `PodAutoscaler` specs in-place to adjust the scale bounds and other parameters.

Networking

A frequently-requested feature is the ability to deploy services which are not exposed externally and can only be accessed by other services in the cluster. In v0.3, Routes configured to use the `svc.cluster.local` domain will only be exposed to the cluster-local Istio gateway. The cluster-local gateway will keep the deployed service inaccessible from outside the cluster. Developers can also use the `serving.knative.dev/visibility=cluster-local` label on their Route or Service to enable this behaviour.

Knative is also deprecating its dedicated Istio gateway. In v0.3 release, Knative will still expose public routes to both the deprecated gateway and the default Istio gateway. Starting with next release however, Knative will remove the deprecated gateway to further reduce overhead and avoid the additional cost of public IP. (Note, you may have to update the gateway IP in your DNS mappings).

Eventing

With the inclusion of Eventing in the previous release, there has been a significant focus on extending the number of and documenting available external event sources which can be installed in Knative as Kubernetes Custom Resource Definitions (CRDs). The complete list of currently supported event sources can be found here.

Build

The Knative Build component can now support both single `source` and multiple input `sources`. If multiple sources are requested, each will be fetched in declared order and placed into a directory under `/workspace` named after the source’s name field. The Build controller is also now subject to the PodSecurityPolicy which enables cluster operators to specify further limitations.

Monitoring

Metric labels should now be consistent across all of the Knative components. Also, in addition to the default Prometheus metric target, Knative control plane metrics (from Reconciler, Autoscaler, and Activator) can now be exported directly to Stackdriver.

Learn more

+
+
diff --git a/blog/releases/_index.md b/blog/releases/_index.md new file mode 100644 index 000000000..f134d14dc --- /dev/null +++ b/blog/releases/_index.md @@ -0,0 +1,5 @@ +--- +title: "Knative releases" +linkTitle: "Releases" +weight: 20 +--- diff --git a/community/_index.md b/community/_index.md new file mode 100644 index 000000000..5b92f247e --- /dev/null +++ b/community/_index.md @@ -0,0 +1,10 @@ +--- +title: Community +menu: + main: + weight: 40 +--- + + + + diff --git a/community/samples/README.md b/community/samples/README.md index 852f3db01..44283be20 100644 --- a/community/samples/README.md +++ b/community/samples/README.md @@ -1,8 +1,5 @@ -# Knative Community Samples +## Sample apps -This directory contains Knative sample applications submitted from the -community. - -| Sample Name | Description | Language(s) | -| ----------- | -------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Hello World | A quick introduction that highlights how to deploy an app using Knative Serving. | [Clojure](./serving/helloworld-clojure/README.md), [Dart](./serving/helloworld-dart/README.md), [Elixir](./serving/helloworld-elixir/README.md), [Haskell](./serving/helloworld-haskell/README.md), [Rust](./serving/helloworld-rust/README.md), [Shell](./serving/helloworld-shell/README.md), [Swift](./serving/helloworld-swift/README.md), [Vertx](./serving/helloworld-vertx/README.md) | +| Sample Name | Knative Component | Description | Language(s) | +| --------------| ----------------- | -------------------------- | ----------------- | +| Hello World | Serving | A quick introduction that highlights how to deploy an app. | [Clojure](./serving/helloworld-clojure/README.md), [Dart](./serving/helloworld-dart/README.md), [Elixir](./serving/helloworld-elixir/README.md), [Haskell](./serving/helloworld-haskell/README.md), [Rust](./serving/helloworld-rust/README.md), [Shell](./serving/helloworld-shell/README.md), [Swift](./serving/helloworld-swift/README.md), [Vertx](./serving/helloworld-vertx/README.md) | diff --git a/community/samples/_index.md b/community/samples/_index.md new file mode 100644 index 000000000..bc10fa25f --- /dev/null +++ b/community/samples/_index.md @@ -0,0 +1,13 @@ +--- +title: "Knative Community Sample Apps" +linkTitle: "Sample Apps" +weight: 100 +type: "docs" +--- + +Get up and running in a language of your choice using one of the community +contributed and maintained sample apps. + +Use the following table to view the instructions and sample code in the knative/docs repo. + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/community/samples/serving/helloworld-clojure/README.md b/community/samples/serving/helloworld-clojure/README.md index dcc0c0342..fbc515115 100644 --- a/community/samples/serving/helloworld-clojure/README.md +++ b/community/samples/serving/helloworld-clojure/README.md @@ -7,7 +7,7 @@ specified, it will use "World" as the TARGET. ## Prerequisites - A Kubernetes cluster with Knative installed. Follow the - [installation instructions](https://github.com/knative/docs/blob/master/install/README.md) + [installation instructions](../../../install/README.md) if you need to create one. - [Docker](https://www.docker.com) installed and running on your local machine, and a Docker Hub account configured (we'll use it for a container registry). diff --git a/community/samples/serving/helloworld-dart/README.md b/community/samples/serving/helloworld-dart/README.md index 5fafbb92f..e64942829 100644 --- a/community/samples/serving/helloworld-dart/README.md +++ b/community/samples/serving/helloworld-dart/README.md @@ -8,7 +8,7 @@ that you can use for testing. It reads in the env variable `TARGET` and prints ## Prerequisites - A Kubernetes cluster with Knative installed. Follow the - [installation instructions](https://github.com/knative/docs/blob/master/install/README.md) + [installation instructions](../../../install/README.md) if you need to create one. - [Docker](https://www.docker.com) installed and running on your local machine, and a Docker Hub account configured (we'll use it for a container registry). diff --git a/community/samples/serving/helloworld-haskell/README.md b/community/samples/serving/helloworld-haskell/README.md index bfcfd8736..84b629f88 100644 --- a/community/samples/serving/helloworld-haskell/README.md +++ b/community/samples/serving/helloworld-haskell/README.md @@ -7,7 +7,7 @@ specified, it will use "World" as the TARGET. ## Prerequisites - A Kubernetes cluster with Knative installed. Follow the - [installation instructions](https://github.com/knative/docs/blob/master/install/README.md) + [installation instructions](../../../install/README.md) if you need to create one. - [Docker](https://www.docker.com) installed and running on your local machine, and a Docker Hub account configured (we'll use it for a container registry). diff --git a/community/samples/serving/helloworld-rust/README.md b/community/samples/serving/helloworld-rust/README.md index 409aa124a..e4f1e8149 100644 --- a/community/samples/serving/helloworld-rust/README.md +++ b/community/samples/serving/helloworld-rust/README.md @@ -8,7 +8,7 @@ TARGET is not specified, it will use "World" as the TARGET. ## Prerequisites - A Kubernetes cluster with Knative installed. Follow the - [installation instructions](https://github.com/knative/docs/blob/master/install/README.md) + [installation instructions](../../../install/README.md) if you need to create one. - [Docker](https://www.docker.com) installed and running on your local machine, and a Docker Hub account configured (we'll use it for a container registry). diff --git a/community/samples/serving/helloworld-shell/README.md b/community/samples/serving/helloworld-shell/README.md index a484b0d48..d35872fa1 100644 --- a/community/samples/serving/helloworld-shell/README.md +++ b/community/samples/serving/helloworld-shell/README.md @@ -7,7 +7,7 @@ variable is not specified, the script uses `World`. ## Prerequisites - A Kubernetes cluster with Knative installed. Follow the - [installation instructions](https://github.com/knative/docs/blob/master/install/README.md) + [installation instructions](../../../install/README.md) if you need to create one. - [Docker](https://www.docker.com) installed and running on your local machine, and a Docker Hub account configured (we'll use it for a container registry). diff --git a/community/samples/serving/helloworld-swift/README.md b/community/samples/serving/helloworld-swift/README.md index 44c35d9c8..29612877b 100644 --- a/community/samples/serving/helloworld-swift/README.md +++ b/community/samples/serving/helloworld-swift/README.md @@ -8,7 +8,7 @@ specified, the app uses "World" as the TARGET. - You must have a Kubernetes cluster with Knative installed. If you need to create a cluster, follow the - [installation instructions](https://github.com/knative/docs/blob/master/install/README.md). + [installation instructions](../../../install/README.md). - You must have [Docker](https://www.docker.com) installed and running on your local machine, and a Docker Hub account configured (used for container registry). diff --git a/community/samples/serving/helloworld-vertx/README.md b/community/samples/serving/helloworld-vertx/README.md index 4ce11cf3d..490766903 100644 --- a/community/samples/serving/helloworld-vertx/README.md +++ b/community/samples/serving/helloworld-vertx/README.md @@ -15,7 +15,7 @@ You must meet the following requirements to complete this sample: - A version of the Knative Serving component installed and running on your Kubernetes cluster. Follow the - [Knative installation instructions](https://github.com/knative/docs/blob/master/install/README.md) + [Knative installation instructions](../../../install/README.md) if you need to create a Knative cluster. - The following software downloaded and install on your loacal machine: - [Java SE 8 or later JDK](http://www.oracle.com/technetwork/java/javase/downloads/index.html). diff --git a/community/CODE-OF-CONDUCT.md b/contributing/CODE-OF-CONDUCT.md similarity index 97% rename from community/CODE-OF-CONDUCT.md rename to contributing/CODE-OF-CONDUCT.md index 42398be71..3cdd794a7 100644 --- a/community/CODE-OF-CONDUCT.md +++ b/contributing/CODE-OF-CONDUCT.md @@ -1,4 +1,9 @@ -# Contributor Covenant Code of Conduct +--- +title: "Contributor covenant code of conduct" +linkTitle: "Code of conduct" +weight: 10 +type: "docs" +--- ## Our Pledge diff --git a/community/CONTRIBUTING.md b/contributing/CONTRIBUTING.md similarity index 92% rename from community/CONTRIBUTING.md rename to contributing/CONTRIBUTING.md index d75c7de53..f6acdee1b 100644 --- a/community/CONTRIBUTING.md +++ b/contributing/CONTRIBUTING.md @@ -1,4 +1,9 @@ -# Contributing to Knative +--- +title: "Knative contributor guidelines" +linkTitle: "Contributing to Knative" +weight: 15 +type: "docs" +--- So, you want to hack on Knative? Yay! @@ -20,19 +25,19 @@ given the same level of review. ## Working groups -The Knative community is organized into a set of -[working groups](WORKING-GROUPS.md). Any contribution to Knative should be +The Knative contributors community is organized into a set of +[working groups](./WORKING-GROUPS.md). Any contribution to Knative should be started by first engaging with the appropriate working group. ## Code of conduct All members of the Knative community must abide by the -[Code of Conduct](CODE-OF-CONDUCT.md). Only by respecting each other can we +[Code of Conduct](./CODE-OF-CONDUCT.md). Only by respecting each other can we develop a productive, collaborative community. ## Team values -We promote and encourage a set of [shared values](VALUES.md) to improve our +We promote and encourage a set of [shared values](./VALUES.md) to improve our productivity and inter-personal interactions. ## Contributor license agreements @@ -54,7 +59,7 @@ our [Team Drive](https://drive.google.com/corp/drive/folders/0APnJ_hRs30R2Uk9PVA) and sending an email to the appropriate working group's mailing list to let people know the doc is there. To get write access to the drive, you'll need to -be a [member](ROLES.md#member) of the Knative organization. +be a [member](./ROLES.md#member) of the Knative organization. We do not yet have a common design document template(TODO). @@ -73,7 +78,7 @@ later join knative-dev if you want immediate access). ## Contributing documentation For more information about contributing to the Knative documentation, see -[DOCS-CONTRIBUTING.md](DOCS-CONTRIBUTING.md). A lot of the information on this +[DOCS-CONTRIBUTING.md](./DOCS-CONTRIBUTING.md). A lot of the information on this page still applies, but you'll find the specifics about the docs process there. ## Contributing a feature @@ -81,7 +86,7 @@ page still applies, but you'll find the specifics about the docs process there. In order to contribute a feature to Knative you'll need to go through the following steps: -- Discuss your idea with the appropriate [working groups](WORKING-GROUPS.md) on +- Discuss your idea with the appropriate [working groups](./WORKING-GROUPS.md) on the working group's mailing list. - Once there is general agreement that the feature is useful, @@ -109,8 +114,8 @@ following steps: your code changes. - Submit PRs to knative/serving with user documentation for your feature, - including usage examples when possible. Add documentation to - [knative/docs/serving](https://github.com/knative/docs/tree/master/serving). + including usage examples when possible. Add documentation to the `serving` + folder of [knative/docs](../serving). _Note that we prefer bite-sized PRs instead of giant monster PRs. It's therefore preferable if you can introduce large features in small, individually-reviewable @@ -165,7 +170,7 @@ This project uses [Prow](https://github.com/kubernetes/test-infra/tree/master/prow) to assign reviewers to the PR, set labels, run tests automatically, and so forth. -See [Reviewing and Merging Pull Requests](REVIEWING.md) for the PR review and +See [Reviewing and Merging Pull Requests](./REVIEWING.md) for the PR review and merge process used for Knative and for more information about [Prow](./REVIEWING.md#prow). diff --git a/community/DOCS-CONTRIBUTING.md b/contributing/DOCS-CONTRIBUTING.md similarity index 98% rename from community/DOCS-CONTRIBUTING.md rename to contributing/DOCS-CONTRIBUTING.md index d634be6d5..7d001f919 100644 --- a/community/DOCS-CONTRIBUTING.md +++ b/contributing/DOCS-CONTRIBUTING.md @@ -1,4 +1,9 @@ -# Contributing to the Knative Documentation +--- +title: "Contributing to the Knative documentation" +linkTitle: "Contributing to docs" +weight: 20 +type: "docs" +--- - [Before you begin](#before-you-begin) - [Contributing to the documentation](#contributing-to-the-documentation) diff --git a/community/README.md b/contributing/README.md similarity index 65% rename from community/README.md rename to contributing/README.md index 29c444313..6b5e9b6c2 100644 --- a/community/README.md +++ b/contributing/README.md @@ -1,7 +1,6 @@ -# Knative Community _Important_. Before proceeding, please review the Knative community -[Code of Conduct](CODE-OF-CONDUCT.md). +[Code of Conduct](./CODE-OF-CONDUCT.md). If you any have questions or concerns, please contact the authors at knative-code-of-conduct@googlegroups.com. @@ -22,25 +21,25 @@ improving docs, giving talks, etc. Other Documents -- [Code of Conduct](CODE-OF-CONDUCT.md) - all contributors must abide by the +- [Code of Conduct](./CODE-OF-CONDUCT.md) - all contributors must abide by the code of conduct -- [Contributing to Knative](CONTRIBUTING.md) - guidelines and advice on becoming +- [Contributing to Knative](./CONTRIBUTING.md) - guidelines and advice on becoming a contributor -- [Working Groups](WORKING-GROUPS.md) - describes our various working groups -- [Working Group Processes](WORKING-GROUP-PROCESSES.md) - describes how working +- [Working Groups](./WORKING-GROUPS.md) - describes our various working groups +- [Working Group Processes](./WORKING-GROUP-PROCESSES.md) - describes how working groups operate -- [Technical Oversight Committee](TECH-OVERSIGHT-COMMITTEE.md) - describes our +- [Technical Oversight Committee](./TECH-OVERSIGHT-COMMITTEE.md) - describes our technical oversight committee -- [Steering Committee](STEERING-COMMITTEE.md) - describes our steering committee -- [Community Roles](ROLES.md) - describes the roles individuals can assume +- [Steering Committee](./STEERING-COMMITTEE.md) - describes our steering committee +- [Community Roles](./ROLES.md) - describes the roles individuals can assume within the Knative community -- [Reviewing and Merging Pull Requests](REVIEWING.md) - how we manage pull +- [Reviewing and Merging Pull Requests](./REVIEWING.md) - how we manage pull requests ## Introduction Knative is a Kubernetes-based platform to build, deploy, and manage modern -serverless workloads. See [Knative docs](https://github.com/knative/docs) for +serverless workloads. See [Knative docs](../docs/README.md) for in-depth information about using Knative. ## Knative authors @@ -56,24 +55,24 @@ Beyond the official documentation there are endless possibilities for combining tools, platforms, languages, and products. By submitting a tutorial you can share your experience and help others who are solving similar problems. -Community tutorials are stored in Markdown files on -[GitHub](./samples/README.md) where they can be reviewed and edited by the -community. +Community tutorials are stored in Markdown files under the `community` folder +[Community Samples](../community/samples/README.md). These documents +are contributed, reviewed, and maintained by the community. -Please submit a Pull Request to the community sample directory under the Knative -component that your tutorial highlights - [Serving](./samples/serving/), -[Eventing](./samples/eventing/), or [Build](./samples/build/). A reviewer will -be assigned to review your submission. They'll work with you to ensure your -submission meets the [style guide](DOCS-CONTRIBUTING.md), but it helps if you -follow it as you write your tutorial. +Submit a Pull Request to the community sample directory under the Knative +component folder that aligns with your document. For example, Knative Serving +samples are under the `serving` folder. A reviewer will be assigned to review your +submission. They'll work with you to ensure that your submission is clear, correct, +and meets the [style guide](./DOCS-CONTRIBUTING.md), but it helps if you follow it +as you write your tutorial. ## Meetings and work groups Knative has public and recorded bi-weekly community meetings. -Each project has one or more [working groups](WORKING-GROUPS.md) driving the +Each project has one or more [working groups](./WORKING-GROUPS.md) driving the project, and Knative as a single -[technical oversight community](TECH-OVERSIGHT-COMMITTEE.md) monitoring the +[technical oversight community](./TECH-OVERSIGHT-COMMITTEE.md) monitoring the overall project. ## How can I help @@ -99,7 +98,7 @@ following resources are available for you: - [Knative Users](https://groups.google.com/forum/#!forum/knative-users) - [Knative Developers](https://groups.google.com/forum/#!forum/knative-dev) -For contributors to Knative, we also have [Knative Slack](SLACK-GUIDELINES.md). +For contributors to Knative, we also have [Knative Slack](./SLACK-GUIDELINES.md). --- diff --git a/community/REVIEWING.md b/contributing/REVIEWING.md similarity index 89% rename from community/REVIEWING.md rename to contributing/REVIEWING.md index 6de442dd9..0149ce1b0 100644 --- a/community/REVIEWING.md +++ b/contributing/REVIEWING.md @@ -1,11 +1,16 @@ -# Reviewing and Merging Pull Requests for Knative +--- +title: "Reviewing and merging Knative pull requests" +linkTitle: "Pull request guidelines" +weight: 60 +type: "docs" +--- As a community, we believe in the value of code reviews for all contributions. Code reviews increase both the quality and readability of our code base, which in turn produces high quality software. This document provides guidelines for how the project's -[Members](ROLES.md#member) review issues and merge pull requests (PRs). +[Members](./ROLES.md#member) review issues and merge pull requests (PRs). - [Pull requests welcome](#pull-requests-welcome) - [Code of Conduct](#code-of-conduct) @@ -25,7 +30,7 @@ Please do not ever hesitate to ask a question or submit a PR. Reviewers are often the first points of contact between new members of the community and are important in shaping the community. We encourage reviewers to -read the [code of conduct](community/CODE-OF-CONDUCT.md) and to go above and +read the [code of conduct](./CODE-OF-CONDUCT.md) and to go above and beyond the code of conduct to promote a collaborative and respectful community. ## Code reviewers @@ -64,7 +69,7 @@ require a rebase are not considered active PRs. ### Holds -Any [Approver](ROLES.md#approver) who wants to review a PR but does not have +Any [Approver](./ROLES.md#approver) who wants to review a PR but does not have time immediately can put a hold on a PR. If you need more time, say so on the PR discussion and offer an ETA measured in single-digit days at most. Any PR that has a hold will not be merged until the person who requested the hold acks the @@ -72,10 +77,10 @@ review, withdraws their hold, or is overruled by a majority of approvers. ## Approvers -Merging of PRs is done by [Approvers](ROLES.md#approver). +Merging of PRs is done by [Approvers](./ROLES.md#approver). As is the case with many open source projects, becoming an Approver is based on -contributions to the project. See our [community roles](ROLES.md) document for +contributions to the project. See our [community roles](./ROLES.md) document for information on how this is done. ## Merging PRs diff --git a/community/ROLES.md b/contributing/ROLES.md similarity index 96% rename from community/ROLES.md rename to contributing/ROLES.md index e9e8d4a6f..382961828 100644 --- a/community/ROLES.md +++ b/contributing/ROLES.md @@ -1,4 +1,9 @@ -# Knative Community Roles +--- +title: "Knative community roles" +linkTitle: "Community roles" +weight: 55 +type: "docs" +--- This document describes the set of roles individuals might have within the Knative community, the requirements of each role, and the privileges that each role @@ -211,15 +216,16 @@ approver in an OWNERS file: - Approver status can be a precondition to accepting large code contributions. -- Demonstrate sound technical judgement. +- Demonstrate sound technical judgment. -- Responsible for project quality control via [code reviews](REVIEWING.md). + +- Responsible for project quality control via [code reviews](./REVIEWING.md). - Focus on holistic acceptance of contribution such as dependencies with other features, backward / forward compatibility, API and flag definitions, etc. - Expected to be responsive to review requests as per - [community expectations](REVIEWING.md). + [community expectations](./REVIEWING.md). - Mentor members and contributors. @@ -258,7 +264,7 @@ Additional requirements for leads of a new working group: The following apply to the area / component for which one would be an owner. - Run their working group as explained in the - [Working Group Processes](WORKING-GROUP-PROCESSES.md). + [Working Group Processes](./WORKING-GROUP-PROCESSES.md). - Design/proposal approval authority over the area / component, though escalation to the technical oversight committee is possible. @@ -273,7 +279,7 @@ The following apply to the area / component for which one would be an owner. - Capable of directly applying lgtm + approve labels for any PR. - Expected to respect OWNERS files approvals and use - [standard procedure for merging code](REVIEWING.md#merging-prs). + [standard procedure for merging code](./REVIEWING.md#merging-prs). - Expected to work to holistically maintain the health of the project through: diff --git a/community/SLACK-GUIDELINES.md b/contributing/SLACK-GUIDELINES.md similarity index 98% rename from community/SLACK-GUIDELINES.md rename to contributing/SLACK-GUIDELINES.md index e11f2425d..ab8cfb7ff 100644 --- a/community/SLACK-GUIDELINES.md +++ b/contributing/SLACK-GUIDELINES.md @@ -1,4 +1,9 @@ -# Slack Usage Guidelines +--- +title: "Slack usage guidelines" +linkTitle: "Slack guidelines" +weight: 45 +type: "docs" +--- Slack is the main communication platform for Knative outside of our mailing lists. It’s important that conversation stays on topic in each channel, and that diff --git a/community/STEERING-COMMITTEE.md b/contributing/STEERING-COMMITTEE.md similarity index 94% rename from community/STEERING-COMMITTEE.md rename to contributing/STEERING-COMMITTEE.md index 057d783ca..726462aa0 100644 --- a/community/STEERING-COMMITTEE.md +++ b/contributing/STEERING-COMMITTEE.md @@ -1,4 +1,9 @@ -# Knative Steering Committee +--- +title: "Knative steering committee" +linkTitle: "Steering committee" +weight: 40 +type: "docs" +--- The Knative Steering Committee (SC) defines, evolves, and defends the vision, values, mission, and scope of the project. _The Steering Committee is a @@ -13,7 +18,7 @@ work-in-progress._ - Non-technical project oversight - Define policy for the creation and administration of community groups, - including [Working Groups](WORKING-GROUPS.md) and Committees. + including [Working Groups](./WORKING-GROUPS.md) and Committees. - Define and evolve project governance structures and policies, including project role assignment and contributor promotion. diff --git a/community/TECH-OVERSIGHT-COMMITTEE.md b/contributing/TECH-OVERSIGHT-COMMITTEE.md similarity index 94% rename from community/TECH-OVERSIGHT-COMMITTEE.md rename to contributing/TECH-OVERSIGHT-COMMITTEE.md index a92c42fc8..3bf0283b8 100644 --- a/community/TECH-OVERSIGHT-COMMITTEE.md +++ b/contributing/TECH-OVERSIGHT-COMMITTEE.md @@ -1,4 +1,9 @@ -# Knative Technical Oversight Committee +--- +title: "Knative technical oversight committee" +linkTitle: "Technical oversight committee" +weight: 35 +type: "docs" +--- The Knative Technical Oversight Committee (TOC) is responsible for cross-cutting product and design decisions. @@ -41,8 +46,8 @@ product and design decisions. community focus - Ensure the team adheres to our - [code of conduct](CONTRIBUTING.md#code-of-conduct) and respects our - [values](VALUES.md). + [code of conduct](./CONTRIBUTING.md#code-of-conduct) and respects our + [values](./VALUES.md). - Foster an environment for a healthy and happy community of developers and contributors. @@ -82,7 +87,7 @@ during the community feedback period at the end of each meeting. ## Committee Members The members of the TOC are shown below. Membership in the TOC is determined by -the [Steering committee](STEERING-COMMITTEE.md). +the [Steering committee](./STEERING-COMMITTEE.md). |   | Member | Company | Profile | | ------------------------------------------------------------- | ------------- | ------- | -------------------------------------------------- | diff --git a/community/VALUES.md b/contributing/VALUES.md similarity index 90% rename from community/VALUES.md rename to contributing/VALUES.md index bfd29023c..2ffad0267 100644 --- a/community/VALUES.md +++ b/contributing/VALUES.md @@ -1,4 +1,9 @@ -# Knative Team Values +--- +title: "Knative team values" +linkTitle: "Team values" +weight: 50 +type: "docs" +--- We want to make sure every member has a shared understanding of the goals and values we hold as a team: @@ -24,14 +29,14 @@ values we hold as a team: applicability of Knative). Empathize with our users. Focus on the specific issue at hand, and remember that we all care about the project, first and foremost. - - Emails to the [mailing lists](CONTRIBUTING.md#contributing-a-feature), + - Emails to the [mailing lists](./CONTRIBUTING.md#contributing-a-feature), document comments, or meetings are often better and higher bandwidth ways to communicate complex and nuanced design issues, as opposed to protracted heated live chats. - Be mindful of the terminology you are using, it may not be the same as someone else and cause misunderstanding. To promote clear and precise communication, define the terms you are using in context. - - See also the [Code of Conduct](CODE-OF-CONDUCT.md), which everyone must + - See also the [Code of Conduct](./CODE-OF-CONDUCT.md), which everyone must abide by. - Raising issues is great, suggesting solutions is even better diff --git a/community/WORKING-GROUP-PROCESSES.md b/contributing/WORKING-GROUP-PROCESSES.md similarity index 96% rename from community/WORKING-GROUP-PROCESSES.md rename to contributing/WORKING-GROUP-PROCESSES.md index 9c3cd1c8d..d9cada3fa 100644 --- a/community/WORKING-GROUP-PROCESSES.md +++ b/contributing/WORKING-GROUP-PROCESSES.md @@ -1,4 +1,9 @@ -# Knative Working Group Processes +--- +title: "Knative working group processes and guidelines" +linkTitle: "Working group guidelines" +weight: 30 +type: "docs" +--- This document describes the processes we use to manage the Knative working groups. This includes how they are formed, how leads are established, how they @@ -96,7 +101,7 @@ working group: group to the meeting. - **Register the Working Group**. Go to - [WORKING-GROUPS.md](https://github.com/knative/serving/blob/master/community/WORKING-GROUPS.md) + [WORKING-GROUPS.md](./WORKING-GROUPS.md) and add your working group name, the names of the leads, the working group charter, and a link to the meeting you created. @@ -128,7 +133,7 @@ representatives from multiple organizations as both leads and members. Working group leads must be Members of the Knative project (that is, have made multiple contributions to the project in the form of code, design, or documentation). -Please see the [Community Roles](ROLES.md) document for a description of a +Please see the [Community Roles](./ROLES.md) document for a description of a lead’s role and requirements. ## Running a working group @@ -184,7 +189,7 @@ Leads from all affected working groups generally work together and come to an agreeable conclusion. In all cases, remaining blocking issues can be raised to the -[technical oversight committee](TECH-OVERSIGHT-COMMITTEE.md) to help resolve the +[technical oversight committee](./TECH-OVERSIGHT-COMMITTEE.md) to help resolve the situation. To trigger an escalation, create an issue in the `knative/serving` repo and assign it to the **@knative/tech-oversight-committee** team. diff --git a/community/WORKING-GROUPS.md b/contributing/WORKING-GROUPS.md similarity index 98% rename from community/WORKING-GROUPS.md rename to contributing/WORKING-GROUPS.md index cb35e30ee..8dcdf87ad 100644 --- a/community/WORKING-GROUPS.md +++ b/contributing/WORKING-GROUPS.md @@ -1,13 +1,18 @@ -# Knative Working Groups +--- +title: "Knative working group" +linkTitle: "Join working groups" +weight: 25 +type: "docs" +--- Most community activity is organized into _working groups_. -Working groups follow the [contributing](CONTRIBUTING.md) guidelines although +Working groups follow the [contributing](./CONTRIBUTING.md) guidelines although each of these groups may operate a little differently depending on their needs and workflow. When the need arises, a new working group can be created. See the -[working group processes](WORKING-GROUP-PROCESSES.md) for working group proposal +[working group processes](./WORKING-GROUP-PROCESSES.md) for working group proposal and creation procedures. The working groups generate design docs which are kept in a @@ -98,7 +103,7 @@ conventions ## Documentation -Knative documentation, especially the [Docs](https://github.com/knative/docs) +Knative documentation, especially the [Docs](../docs/README.md) repo. | Artifact | Link | diff --git a/contributing/_index.md b/contributing/_index.md new file mode 100644 index 000000000..a2adc4649 --- /dev/null +++ b/contributing/_index.md @@ -0,0 +1,18 @@ +--- +title: "Knative contribution guidelines" +linkTitle: "Contributing" +weight: 20 +type: "docs" +menu: + main: + weight: 60 +aliases: + - /docs/contribution-guidelines/ +--- + +Learn how to join the community of Knative contributors. + +Also see our [Community page](../community) for links to Knative chats, discussions, or Q&A. + + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/doc-releases.md b/doc-releases.md index fb47d35c6..f0805f442 100644 --- a/doc-releases.md +++ b/doc-releases.md @@ -7,6 +7,7 @@ the version that matches your installed version of Knative. ### Released versions +- [Branch: **`release-0.3`**](https://github.com/knative/docs/tree/release-0.3) - [Branch: **`release-0.2`**](https://github.com/knative/docs/tree/release-0.2) - [Branch: **`release-0.1`**](https://github.com/knative/docs/tree/release-0.1) diff --git a/docs/README.md b/docs/README.md index a3afa005d..1fb6085fa 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,9 +1,9 @@ -# Welcome to Knative -Knative (pronounced kay-nay-tiv) extends Kubernetes to provide a set of -middleware components that are essential to build modern, source-centric, and -container-based applications that can run anywhere: on premises, in the cloud, -or even in a third-party data center. +Knative (pronounced kay-nay-tiv) extends +[Kubernetes](https://kubernetes.io/docs/concepts/overview/what-is-kubernetes/) +to provide a set of middleware components that are essential to build modern, +source-centric, and container-based applications that can run anywhere: on +premises, in the cloud, or even in a third-party data center. Each of the components under the Knative project attempt to identify common patterns and codify the best practices that are shared by successful, @@ -13,8 +13,8 @@ focus on solving mundane but difficult tasks such as: - [Deploying a container](./install/getting-started-knative-app.md) - [Orchestrating source-to-URL workflows on Kubernetes](./serving/samples/source-to-url-go/) - [Routing and managing traffic with blue/green deployment](./serving/samples/blue-green-deployment.md) -- [Scaling automatically and sizing workloads based on demand](./serving/samples/autoscale-go) -- [Binding running services to eventing ecosystems](./eventing/samples/kubernetes-event-source) +- [Scaling automatically and sizing workloads based on demand](./serving/samples/autoscale-go/) +- [Binding running services to eventing ecosystems](./eventing/samples/kubernetes-event-source/) Developers on Knative can use familiar idioms, languages, and frameworks to deploy functions, applications, or containers workloads. @@ -61,8 +61,8 @@ separation between pluggable components, the Knative project establishes an efficient contributor workflow. Knative is a diverse, open, and inclusive community. To get involved, see -[CONTRIBUTING.md](./community/CONTRIBUTING.md) and join the -[Knative community](./community/README.md). +[CONTRIBUTING.md](../contributing/CONTRIBUTING.md) and join the +[Knative community](../community/). Your own path to becoming a Knative contributor can [begin anywhere](https://github.com/knative/serving/issues?q=is%3Aissue+is%3Aopen+sort%3Aupdated-desc+label%3Akind%2Fgood-first-issue). @@ -92,7 +92,7 @@ Follow the links below to learn more about Knative. - [Autoscaling](./serving/samples/autoscale-go/README.md) - [Source-to-URL deployment](./serving/samples/source-to-url-go/README.md) -- [Binding running services to eventing ecosystems](./eventing/samples/kubernetes-event-source) +- [Binding running services to eventing ecosystems](./eventing/samples/kubernetes-event-source/) - [Telemetry](./serving/samples/telemetry-go/README.md) - [REST API sample](./serving/samples/rest-api-go/README.md) - [All samples for serving](./serving/samples/) diff --git a/docs/_index.md b/docs/_index.md new file mode 100755 index 000000000..664511543 --- /dev/null +++ b/docs/_index.md @@ -0,0 +1,8 @@ +--- +title: "Welcome to Knative" +linkTitle: "Documentation" +weight: 10 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/build/README.md b/docs/build/README.md index bb98afa9f..e12b33160 100644 --- a/docs/build/README.md +++ b/docs/build/README.md @@ -1,4 +1,3 @@ -# Knative Build A `Build` is a custom resource in Knative that allows you to define a process that runs to completion and can provide status. For example, fetch, build, and @@ -13,9 +12,9 @@ action, you can define a Knative `Build` through a single configuration file. Also consider using a Knative `Build` to build the source code of your apps into container images, which you can then run on -[Knative `serving`](https://github.com/knative/docs/blob/master/serving/README.md). +[Knative `serving`](../serving/README.md). More information about this use case is demonstrated in -[this sample](https://github.com/knative/docs/blob/master/serving/samples/source-to-url-go). +[this sample](../serving/samples/source-to-url-go). ## Key features of Knative Builds @@ -36,10 +35,10 @@ More information about this use case is demonstrated in See the following reference topics for information about each of the build components: -- [`Build`](https://github.com/knative/docs/blob/master/build/builds.md) -- [`BuildTemplate`](https://github.com/knative/docs/blob/master/build/build-templates.md) -- [`Builder`](https://github.com/knative/docs/blob/master/build/builder-contract.md) -- [`ServiceAccount`](https://github.com/knative/docs/blob/master/build/auth.md) +- [`Build`](./builds.md) +- [`BuildTemplate`](./build-templates.md) +- [`Builder`](./builder-contract.md) +- [`ServiceAccount`](./auth.md) ## Install the Knative Build component @@ -53,7 +52,7 @@ in your Kubernetes cluster: cluster, see [Installing Knative](../install/README.md). - If you have a component of Knative installed and running, you can - [add and install the Knative Build component](installing-build-component.md). + [add and install the Knative Build component](./installing-build-component.md). ## Configuration syntax example @@ -104,7 +103,7 @@ builds. #### Complex samples -- [Use Knative to build apps from source code and then run those containers](https://github.com/knative/docs/blob/master/serving/samples/source-to-url-go). +- [Use Knative to build apps from source code and then run those containers](../serving/samples/source-to-url-go). ## Related info diff --git a/docs/build/_index.md b/docs/build/_index.md new file mode 100644 index 000000000..1a4b900b4 --- /dev/null +++ b/docs/build/_index.md @@ -0,0 +1,8 @@ +--- +title: "Knative Build" +linkTitle: "Build Component" +weight: 20 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/build/auth.md b/docs/build/auth.md index 503a98296..f66acc55c 100644 --- a/docs/build/auth.md +++ b/docs/build/auth.md @@ -1,4 +1,8 @@ -# Authentication +--- +title: "Authentication" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 25 +--- This document defines how authentication is provided during execution of a build. diff --git a/docs/build/build-templates.md b/docs/build/build-templates.md index 07aa5a70f..3c6ddf282 100644 --- a/docs/build/build-templates.md +++ b/docs/build/build-templates.md @@ -1,4 +1,8 @@ -# Build Templates +--- +title: "Build templates" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 35 +--- This document defines "Build Templates" and their capabilities. diff --git a/docs/build/builder-contract.md b/docs/build/builder-contract.md index 02bb2720c..9266bb655 100644 --- a/docs/build/builder-contract.md +++ b/docs/build/builder-contract.md @@ -1,4 +1,8 @@ -# Builders +--- +title: "Builders" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 15 +--- This document defines builder images and the conventions to which they are expected to adhere. diff --git a/docs/build/builds.md b/docs/build/builds.md index 661cb7a2c..cc9f89885 100644 --- a/docs/build/builds.md +++ b/docs/build/builds.md @@ -1,4 +1,8 @@ -# Knative `Build` resources +--- +title: "Knative `Build` resources" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 5 +--- Use the `Build` resource object to create and run on-cluster processes to completion. diff --git a/docs/build/creating-builds.md b/docs/build/creating-builds.md index 4954384ae..980fef038 100644 --- a/docs/build/creating-builds.md +++ b/docs/build/creating-builds.md @@ -1,4 +1,8 @@ -# Creating a simple Knative Build +--- +title: "Creating a simple Knative build" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 30 +--- Use this page to learn how to create and then run a simple build in Knative. In this topic, you create a Knative Build configuration file for a simple app, @@ -10,7 +14,7 @@ uses [busybox](https://docs.docker.com/samples/library/busybox/) to simply print "_hello build_". Tip: See the -[build code samples](builds.md#get-started-with-knative-build-samples) for +[build code samples](./builds.md#get-started-with-knative-build-samples) for examples of more complex builds, including code samples that use container images, authentication, and include multiple steps. @@ -23,14 +27,14 @@ Kubernetes cluster, and it must include the Knative Build component: cluster, see [Installing Knative](../install/README.md). - If you have a component of Knative installed and running, you must - [ensure that the Knative Build component is also installed](installing-build-component.md). + [ensure that the Knative Build component is also installed](./installing-build-component.md). ## Creating and running a build 1. Create a configuration file named `build.yaml` that includes the following code. - This `Build` resource definition includes a single "[step](builds.md#steps)" + This `Build` resource definition includes a single "[step](./builds.md#steps)" that performs the task of simply printing "_hello build_": ```yaml @@ -48,7 +52,7 @@ Kubernetes cluster, and it must include the Knative Build component: Notice that this definition specifies `kind` as a `Build`, and that the name of this `Build` resource is `hello-build`. For more information about defining build configuration files, See the - [`Build` reference topic](builds.md). + [`Build` reference topic](./builds.md). 1. Deploy the `build.yaml` configuration file and run the `hello-build` build on Knative by running the @@ -160,7 +164,7 @@ Kubernetes cluster, and it must include the Knative Build component: To learn more about the objects and commands used in this topic, see: -- [Knative `Build` resources](builds.md) +- [Knative `Build` resources](./builds.md) - [Kubernetes Init containers](https://kubernetes.io/docs/concepts/workloads/pods/init-containers/) - [Kubernetes kubectl CLI](https://kubernetes.io/docs/reference/kubectl/kubectl/) diff --git a/docs/build/installing-build-component.md b/docs/build/installing-build-component.md index f1b544396..2f33d5387 100644 --- a/docs/build/installing-build-component.md +++ b/docs/build/installing-build-component.md @@ -1,4 +1,8 @@ -# Installing the Knative Build component +--- +title: "Installing the Knative Build component" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 10 +--- Before you can run a Knative Build, you must install the Knative Build component in your Kubernetes cluster. Use this page to add the Knative Build component to @@ -38,7 +42,7 @@ To add only the Knative Build component to an existing installation: time. Use CTRL + C to exit watch mode. You are now ready to create and run Knative Builds, see -[Creating a simple Knative Build](../build/creating-builds.md) to get started. +[Creating a simple Knative Build](./creating-builds.md) to get started. --- diff --git a/docs/build/personas.md b/docs/build/personas.md index 689850be3..eacc52d84 100644 --- a/docs/build/personas.md +++ b/docs/build/personas.md @@ -1,4 +1,8 @@ -# Knative Personas +--- +title: "Knative personas" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 20 +--- When discussing user actions, it is often helpful to [define specific user roles]() diff --git a/docs/concepts/_index.md b/docs/concepts/_index.md new file mode 100755 index 000000000..023fbd4b5 --- /dev/null +++ b/docs/concepts/_index.md @@ -0,0 +1,7 @@ +--- +title: "Knative Concepts" +linkTitle: "Concepts" +weight: 89 +--- + +Learn about Knative. diff --git a/docs/concepts/resources.md b/docs/concepts/resources.md index f308251b2..e70477476 100644 --- a/docs/concepts/resources.md +++ b/docs/concepts/resources.md @@ -1,4 +1,7 @@ -# Resources +--- +title: "Resources" +weight: 10 +--- This page contains information about various tools and technologies that are useful to anyone developing on Knative. @@ -58,7 +61,7 @@ Docker daemon, which would give the build complete access to your entire cluster. So that's a very bad idea. `kaniko` expects to run inside a container, so it's a natural fit for the Build -CRD [builder contract](...). `kaniko` is available as a builder at +CRD [builder contract](../build/builder-contract.md). `kaniko` is available as a builder at `gcr.io/kaniko-project/executor:latest`, and there's a `BuildTemplate` that wraps it at https://github.com/knative/build-templates/blob/master/kaniko/kaniko.yaml. It diff --git a/docs/eventing/README.md b/docs/eventing/README.md index dca408610..a13dbd7ab 100644 --- a/docs/eventing/README.md +++ b/docs/eventing/README.md @@ -1,4 +1,3 @@ -# Knative Eventing Knative Eventing is a system that is designed to address a common need for cloud native development and provides composable primitives to enable late-binding @@ -62,7 +61,7 @@ event sources. Sources manage registration and delivery of events from external systems using Kubernetes [Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/). Learn more about Eventing development in the -[Eventing work group](https://github.com/knative/docs/blob/master/community/WORKING-GROUPS.md#events). +[Eventing work group](../../contributing/WORKING-GROUPS.md#events). ## Installation @@ -111,13 +110,13 @@ The eventing infrastructure supports two forms of event delivery at the moment: to the requested destinations and should buffer the events if the destination Service is unavailable. -![Control plane object model](control-plane.png) +![Control plane object model](./images/control-plane.png) The actual message forwarding is implemented by multiple data plane components which provide observability, persistence, and translation between different messaging protocols. -![Data plane implementation](data-plane.png) +![Data plane implementation](./images/data-plane.png) @@ -132,7 +131,7 @@ part of the `sources` category, so you can list all existing Sources with `kubectl get sources`. The currently-implemented Sources are described below: _Want to implement your own source? Check out -[the tutorial](samples/writing-a-source/README.md)._ +[the tutorial](./samples/writing-a-source/README.md)._ ### KubernetesEventSource @@ -258,11 +257,11 @@ See the [Cronjob Source](samples/cronjob-source) example. - [Setup Knative Serving](../install/README.md) - [Install Eventing components](#installation) -- [Run samples](samples/) +- [Run samples](./samples/) ## Configuration -- [Default Channels](channels/default-channels.md) provide a way to choose the +- [Default Channels](./channels/default-channels.md) provide a way to choose the persistence strategy for Channels across the cluster. --- diff --git a/docs/eventing/_index.md b/docs/eventing/_index.md new file mode 100644 index 000000000..dd4871dde --- /dev/null +++ b/docs/eventing/_index.md @@ -0,0 +1,8 @@ +--- +title: "Knative Eventing" +linkTitle: "Eventing Component" +weight: 60 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/eventing/channels/README.md b/docs/eventing/channels/README.md index 10271e6c5..daf15416c 100644 --- a/docs/eventing/channels/README.md +++ b/docs/eventing/channels/README.md @@ -10,8 +10,6 @@ procedure: ``` --> -# Knative Channels - Channels are Kubernetes Custom Resources which define a single event forwarding and persistence layer. Messaging implementations may provide implementations of Channels via the diff --git a/docs/eventing/channels/_index.md b/docs/eventing/channels/_index.md new file mode 100644 index 000000000..bddd22c96 --- /dev/null +++ b/docs/eventing/channels/_index.md @@ -0,0 +1,8 @@ +--- +title: "Knative Eventing channels" +linkTitle: "Eventing channels" +weight: 40 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/eventing/channels/default-channels.md b/docs/eventing/channels/default-channels.md index 576bcd3e7..4ad3e3365 100644 --- a/docs/eventing/channels/default-channels.md +++ b/docs/eventing/channels/default-channels.md @@ -1,4 +1,7 @@ -# Default Channels +--- +title: "Default channels" +weight: 2 +--- The default channel configuration allows channels to be created without specifying a provisioner. This leaves the selection of channel provisioner and diff --git a/docs/eventing/channels/generator/ReadmeTemplate.gomd b/docs/eventing/channels/generator/ReadmeTemplate.gomd index d4c5bdd9b..6b845d33d 100644 --- a/docs/eventing/channels/generator/ReadmeTemplate.gomd +++ b/docs/eventing/channels/generator/ReadmeTemplate.gomd @@ -13,8 +13,6 @@ procedure: ``` --> -# Knative Channels - Channels are Kubernetes Custom Resources which define a single event forwarding and persistence layer. Messaging implementations may provide implementations of Channels via the [ClusterChannelProvisioner](https://github.com/knative/eventing/blob/master/pkg/apis/eventing/v1alpha1/cluster_channel_provisioner_types.go#L35) diff --git a/docs/eventing/channels/generator/main.go b/docs/eventing/channels/generator/main.go index b6f8bc636..111385a56 100644 --- a/docs/eventing/channels/generator/main.go +++ b/docs/eventing/channels/generator/main.go @@ -30,7 +30,7 @@ import ( var ( yamlFile = flag.String("yaml", "eventing/channels/channels.yaml", "The YAML file to parse to generate the mark down.") templateFile = flag.String("template", "eventing/channels/generator/ReadmeTemplate.gomd", "The template file to fill in.") - mdFile = flag.String("md", "eventing/channels/README.md", "The mark down file to write to. Any existing file will be overwritten.") + mdFile = flag.String("md", "eventing/channels/", "The mark down file to write to. Any existing file will be overwritten.") ) func main() { diff --git a/docs/eventing/debugging/README.md b/docs/eventing/debugging/README.md index 18e117ec2..aa0318b94 100644 --- a/docs/eventing/debugging/README.md +++ b/docs/eventing/debugging/README.md @@ -1,12 +1,11 @@ -# Debugging Knative Eventing This is an evolving document on how to debug a non-working Knative Eventing setup. ## Audience -This document is intended for people that are familiar with -[Knative Eventing](../README.md)'s object model. You don't need to be an expert, +This document is intended for people that are familiar with the object model of +[Knative Eventing](../README.md). You don't need to be an expert, but do need to know roughly how things fit together. ## Version diff --git a/docs/eventing/debugging/_index.md b/docs/eventing/debugging/_index.md new file mode 100644 index 000000000..1469b70a4 --- /dev/null +++ b/docs/eventing/debugging/_index.md @@ -0,0 +1,8 @@ +--- +title: "Debugging Knative Eventing" +linkTitle: "Debugging" +weight: 80 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/eventing/default-channels.md b/docs/eventing/default-channels.md new file mode 100644 index 000000000..576bcd3e7 --- /dev/null +++ b/docs/eventing/default-channels.md @@ -0,0 +1,131 @@ +# Default Channels + +The default channel configuration allows channels to be created without +specifying a provisioner. This leaves the selection of channel provisioner and +properties up to the operator. The operator controls the default settings via a +ConfigMap. + +## Creating a default channel + +To create a default channel, leave the `spec.provisioner` property blank. The +`spec` property must be provided, but should be empty. + +_The content of `spec.arguments` will be cleared for default channels._ + +This is a valid default channel: + +```yaml +apiVersion: eventing.knative.dev/v1alpha1 +kind: Channel +metadata: + name: default-channel + namespace: default +spec: {} +``` + +When the above Channel is created, a mutating admission webhook sets +`spec.provisioner` based on the default provisioner chosen by the operator. + +For example, if the default provisioner is named `default-provisioner`: + +```yaml +apiVersion: eventing.knative.dev/v1alpha1 +kind: Channel +metadata: + name: default-channel + namespace: default +spec: + provisioner: + apiversion: eventing.knative.dev/v1alpha1 + kind: ClusterChannelProvisioner + name: default-provisioner +``` + +### Caveats + +#### Arguments cannot be specified by default channels + +Currently (v0.3), default channels do not support specifying arguments. If +`spec.arguments` is set when creating a default channel, it will be cleared. +Arguments for default channels may be supported in future versions. + +For example: + +```yaml +apiVersion: eventing.knative.dev/v1alpha1 +kind: Channel +metadata: + name: default-channel + namespace: default +spec: + arguments: + foo: bar +``` + +Creating the above channel will produce this result: + +```yaml +apiVersion: eventing.knative.dev/v1alpha1 +kind: Channel +metadata: + name: default-channel + namespace: default +spec: + provisioner: + apiversion: eventing.knative.dev/v1alpha1 + kind: ClusterChannelProvisioner + name: default-provisioner +``` + +## Setting the default channel configuration + +The default channel configuration is specified in the ConfigMap named +`default-channel-webhook` in the `knative-eventing` namespace. This ConfigMap +may specify a cluster-wide default channel provisioner and namespace-specific +channel provisioners. + +_The namespace-specific defaults override the cluster default for channels +created in the specified namespace._ + +_Currently (v0.3) default channel arguments cannot be specified, so all default +channels will have empty arguments. Arguments may be supported in future +versions._ + +The default options are specified like this: + +```yaml +apiVersion: v1 +kind: ConfigMap +metadata: + name: default-channel-webhook + namespace: knative-eventing +data: + default-channel-config: | + clusterdefault: + apiversion: eventing.knative.dev/v1alpha1 + kind: ClusterChannelProvisioner + name: in-memory-channel + namespacedefaults: + some-namespace: + apiversion: eventing.knative.dev/v1alpha1 + kind: ClusterChannelProvisioner + name: some-other-provisioner +``` + +Namespace-specific default take precedence when matched. In the above example, a +Channel created in the `some-namespace` namespace will receive the +`some-other-provisioner` provisioner, not the `in-memory-channel` provisioner. + +### Caveats + +#### Defaults only apply on channel creation + +Defaults are applied by the webhook on Channel creation only. If the default +settings change, the new defaults will apply to newly-created channels only. +Existing channels will not change. + +#### Default channel arguments cannot be specified + +Because the `default-channel-webhook` ConfigMap doesn't allow for specifying +default arguments, all default channels will have empty arguments, even if they +were initially specified in the create request. diff --git a/docs/eventing/control-plane.png b/docs/eventing/images/control-plane.png similarity index 100% rename from docs/eventing/control-plane.png rename to docs/eventing/images/control-plane.png diff --git a/docs/eventing/data-plane.png b/docs/eventing/images/data-plane.png similarity index 100% rename from docs/eventing/data-plane.png rename to docs/eventing/images/data-plane.png diff --git a/docs/eventing/samples/_index.md b/docs/eventing/samples/_index.md new file mode 100644 index 000000000..ebfbb5f5c --- /dev/null +++ b/docs/eventing/samples/_index.md @@ -0,0 +1,6 @@ +--- +title: "Knative Eventing samples" +linkTitle: "Sample apps" +weight: 60 +type: "docs" +--- diff --git a/docs/eventing/samples/cronjob-source/README.md b/docs/eventing/samples/cronjob-source/README.md index e46b171d0..1fefeb53c 100644 --- a/docs/eventing/samples/cronjob-source/README.md +++ b/docs/eventing/samples/cronjob-source/README.md @@ -1,4 +1,3 @@ -# Cron Job Source example Cron Job Source example shows how to configure Cron Job as event source for functions. @@ -7,9 +6,9 @@ functions. ### Prerequisites -1. Setup [Knative Serving](https://github.com/knative/docs/tree/master/serving). +1. Setup [Knative Serving](../../../serving). 1. Setup - [Knative Eventing](https://github.com/knative/docs/tree/master/eventing). + [Knative Eventing](../../../eventing). ### Create a Knative Service diff --git a/docs/eventing/samples/cronjob-source/_index.md b/docs/eventing/samples/cronjob-source/_index.md new file mode 100644 index 000000000..609655485 --- /dev/null +++ b/docs/eventing/samples/cronjob-source/_index.md @@ -0,0 +1,8 @@ +--- +title: "Cron job source example" +linkTitle: "Cron job source" +weight: 10 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/eventing/samples/gcp-pubsub-source/README.md b/docs/eventing/samples/gcp-pubsub-source/README.md index e296a8c82..f18618245 100644 --- a/docs/eventing/samples/gcp-pubsub-source/README.md +++ b/docs/eventing/samples/gcp-pubsub-source/README.md @@ -1,4 +1,3 @@ -# GCP Cloud Pub/Sub - Source This sample shows how to configure the GCP PubSub event source. This event source is most useful as a bridge from other GCP services, such as @@ -16,10 +15,10 @@ source is most useful as a bridge from other GCP services, such as project id, and also set your project ID as default using `gcloud config set project $PROJECT_ID`. -1. Setup [Knative Serving](https://github.com/knative/docs/blob/master/install) +1. Setup [Knative Serving](../../../install) 1. Setup - [Knative Eventing](https://github.com/knative/docs/tree/master/eventing). In + [Knative Eventing](../../../eventing). In addition, install the GCP PubSub event source from `release-gcppubsub.yaml`: ```shell diff --git a/docs/eventing/samples/gcp-pubsub-source/_index.md b/docs/eventing/samples/gcp-pubsub-source/_index.md new file mode 100644 index 000000000..03a199da7 --- /dev/null +++ b/docs/eventing/samples/gcp-pubsub-source/_index.md @@ -0,0 +1,8 @@ +--- +title: "GCP Cloud Pub/Sub source" +linkTitle: "Pub/Sub source" +weight: 20 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/eventing/samples/github-source/README.md b/docs/eventing/samples/github-source/README.md index 5817d7db0..700c05867 100644 --- a/docs/eventing/samples/github-source/README.md +++ b/docs/eventing/samples/github-source/README.md @@ -1,4 +1,3 @@ -# GitHub Source example GitHub Source example shows how to wire GitHub events for consumption by a Knative Service. @@ -10,15 +9,14 @@ by a Knative Service. You will need: 1. An internet-accessible Kubernetes cluster with Knative Serving - installed. Follow the [installation - instructions](https://github.com/knative/docs/blob/master/install/README.md) + installed. Follow the [installation instructions](../../../install/README.md) if you need to create one. 1. Ensure Knative Serving is [configured with a domain - name](https://github.com/knative/docs/blob/master/serving/using-a-custom-domain.md) + name](../../../serving/using-a-custom-domain.md) that allows GitHub to call into the cluster. -1. If you're using GKE, you'll also want to [assign a static IP address](https://github.com/knative/docs/blob/master/serving/gke-assigning-static-ip-address.md). +1. If you're using GKE, you'll also want to [assign a static IP address](../../../serving/gke-assigning-static-ip-address.md). 1. Install [Knative - Eventing](https://github.com/knative/docs/tree/master/eventing). Those + Eventing](../../../eventing). Those instructions also install the default eventing sources, including the `GitHubSource` we'll use. @@ -54,7 +52,7 @@ Create a [personal access token](https://github.com/settings/tokens) for GitHub that the GitHub source can use to register webhooks with the GitHub API. Also decide on a secret token that your code will use to authenticate the incoming webhooks from GitHub (_secretToken_). - + The token can be named anything you find convenient. The Source requires `repo:public_repo` and `admin:repo_hook`, to let it fire events from your public repositories and to create webhooks for those diff --git a/docs/eventing/samples/github-source/_index.md b/docs/eventing/samples/github-source/_index.md new file mode 100644 index 000000000..69b844b80 --- /dev/null +++ b/docs/eventing/samples/github-source/_index.md @@ -0,0 +1,8 @@ +--- +title: "GitHub source" +linkTitle: "GitHub source" +weight: 30 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/eventing/samples/iot-core/README.md b/docs/eventing/samples/iot-core/README.md index de11fd11b..dd2803417 100644 --- a/docs/eventing/samples/iot-core/README.md +++ b/docs/eventing/samples/iot-core/README.md @@ -1,4 +1,3 @@ -# Sample: Binding running services to an IoT core This sample shows how to bind a running service to an [IoT core](https://cloud.google.com/iot-core/) using @@ -68,7 +67,7 @@ export IOTCORE_TOPIC_DEVICE="iot-demo-device-pubsub-topic" ``` 1. Setup - [Knative Eventing](https://github.com/knative/docs/tree/master/eventing). + [Knative Eventing](../../../eventing). 1. Install the [in-memory `ClusterChannelProvisioner`](https://github.com/knative/eventing/tree/master/config/provisioners/in-memory-channel). diff --git a/docs/eventing/samples/iot-core/_index.md b/docs/eventing/samples/iot-core/_index.md new file mode 100644 index 000000000..4be7c6c77 --- /dev/null +++ b/docs/eventing/samples/iot-core/_index.md @@ -0,0 +1,8 @@ +--- +title: "Binding running services to an IoT core" +linkTitle: "IoT core" +weight: 40 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/eventing/samples/kubernetes-event-source/README.md b/docs/eventing/samples/kubernetes-event-source/README.md index d15051a2a..1cc46113d 100644 --- a/docs/eventing/samples/kubernetes-event-source/README.md +++ b/docs/eventing/samples/kubernetes-event-source/README.md @@ -1,4 +1,3 @@ -# Kubernetes Event Source example Kubernetes Event Source example shows how to wire kubernetes cluster events for consumption by a function that has been implemented as a Knative Service. @@ -7,9 +6,9 @@ consumption by a function that has been implemented as a Knative Service. ### Prerequisites -1. Setup [Knative Serving](https://github.com/knative/docs/tree/master/serving). +1. Setup [Knative Serving](../../../serving). 1. Setup - [Knative Eventing](https://github.com/knative/docs/tree/master/eventing). + [Knative Eventing](../../../eventing). ### Channel diff --git a/docs/eventing/samples/kubernetes-event-source/_index.md b/docs/eventing/samples/kubernetes-event-source/_index.md new file mode 100644 index 000000000..9ce2db823 --- /dev/null +++ b/docs/eventing/samples/kubernetes-event-source/_index.md @@ -0,0 +1,8 @@ +--- +title: "Kubernetes event source" +linkTitle: "Kubernetes event" +weight: 50 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/eventing/samples/writing-a-source/01-bootstrap.md b/docs/eventing/samples/writing-a-source/01-bootstrap.md index 83d1e6910..055e6fd4d 100644 --- a/docs/eventing/samples/writing-a-source/01-bootstrap.md +++ b/docs/eventing/samples/writing-a-source/01-bootstrap.md @@ -1,4 +1,7 @@ -# Bootstrap the Project +--- +title: "Bootstrap the project" +weight: 10 +--- We'll use Kubebuilder to bootstrap the project and provide common controller boilerplate and scaffolding. Check out the @@ -50,4 +53,4 @@ your project's vendor directory. The result of this command in the reference project can be viewed at https://github.com/grantr/sample-source/pull/1. -Next: [Define The Source Resource](02-define-source.md) +Next: [Define The Source Resource](./02-define-source.md) diff --git a/docs/eventing/samples/writing-a-source/02-define-source.md b/docs/eventing/samples/writing-a-source/02-define-source.md index a9929f250..999338beb 100644 --- a/docs/eventing/samples/writing-a-source/02-define-source.md +++ b/docs/eventing/samples/writing-a-source/02-define-source.md @@ -1,4 +1,7 @@ -# Define The Source Resource +--- +title: "Define the source resource" +weight: 20 +--- We'll use Kubebuilder to generate a new Kubernetes Custom Resource for our source. Check out the [Kubebuilder book](https://book.kubebuilder.io/) to learn @@ -199,4 +202,4 @@ make These edits in the reference project can be viewed at https://github.com/grantr/sample-source/pull/4. -Next: [Reconcile Sources](03-reconcile-sources.md) +Next: [Reconcile Sources](./03-reconcile-sources.md) diff --git a/docs/eventing/samples/writing-a-source/03-reconcile-sources.md b/docs/eventing/samples/writing-a-source/03-reconcile-sources.md index 07ce22d27..07835d780 100644 --- a/docs/eventing/samples/writing-a-source/03-reconcile-sources.md +++ b/docs/eventing/samples/writing-a-source/03-reconcile-sources.md @@ -1,4 +1,7 @@ -# Reconcile Sources +--- +title: "Reconcile sources" +weight: 30 +--- Now that we have a Source CRD defined with Sink and SinkURI fields, we'll need to use those fields in the Source controller to resolve Sink references and set @@ -215,4 +218,4 @@ g.Eventually(func() error { These edits in the reference project can be viewed at https://github.com/grantr/sample-source/pull/9. -Next: [Publish to Cluster](04-publish-to-cluster.md) +Next: [Publish to Cluster](./04-publish-to-cluster.md) diff --git a/docs/eventing/samples/writing-a-source/04-publish-to-cluster.md b/docs/eventing/samples/writing-a-source/04-publish-to-cluster.md index a5b760e08..45bbe3cf6 100644 --- a/docs/eventing/samples/writing-a-source/04-publish-to-cluster.md +++ b/docs/eventing/samples/writing-a-source/04-publish-to-cluster.md @@ -1,4 +1,7 @@ -# Publish to a Kubernetes Cluster +--- +title: "Publish to a Kubernetes cluster" +weight: 40 +--- So far we've only tested the controller code locally. Now we'd like to deploy it to a cluster and test it working. @@ -193,4 +196,4 @@ kubectl get pods -n sample-source-system Now you can use the verification procedure outlined above in [Create a sample source](#create-a-sample-source). -Next: Dispatching Events +(TODO) Next: Dispatching Events diff --git a/docs/eventing/samples/writing-a-source/README.md b/docs/eventing/samples/writing-a-source/README.md index 627b50acb..76d066314 100644 --- a/docs/eventing/samples/writing-a-source/README.md +++ b/docs/eventing/samples/writing-a-source/README.md @@ -1,4 +1,3 @@ -# Writing an Event Source the Hard Way This tutorial walks you through creating an event source for Knative Eventing "the hard way", without using helper objects like ContainerSource. @@ -29,19 +28,19 @@ You'll need these tools installed: ## Steps -- [Bootstrap Project](01-bootstrap.md) -- [Define The Source Resource](02-define-source.md) -- [Reconcile Sources](03-reconcile-sources.md) -- [Publish to Cluster](04-publish-to-cluster.md) -- Dispatching Events +1. [Bootstrap Project](./01-bootstrap.md) +1. [Define The Source Resource](./02-define-source.md) +1. [Reconcile Sources](./03-reconcile-sources.md) +1. [Publish to Cluster](./04-publish-to-cluster.md) +1. (TODO) Dispatching Events ## Alternatives Kubebuilder not your thing? Prefer the easy way? Check out these alternatives. -- [ContainerSource](https://github.com/knative/docs/tree/master/eventing/sources#meta-sources) +- [ContainerSource](../../../eventing/sources/README.md#meta-sources) is an easy way to turn any dispatcher container into an Event Source. -- [Auto ContainerSource](https://github.com/knative/docs/tree/master/eventing/sources#meta-sources) +- [Auto ContainerSource](../../../eventing/sources/README.md#meta-sources) is an even easier way to turn any dispatcher container into an Event Source without writing any controller code. It requires Metacontroller. - [Metacontroller](https://metacontroller.app) can be used to write controllers diff --git a/docs/eventing/samples/writing-a-source/_index.md b/docs/eventing/samples/writing-a-source/_index.md new file mode 100644 index 000000000..4ffcf355e --- /dev/null +++ b/docs/eventing/samples/writing-a-source/_index.md @@ -0,0 +1,8 @@ +--- +title: "Writing an eventing source the hard way" +linkTitle: "Writing an eventing source" +weight: 60 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/eventing/sources/README.md b/docs/eventing/sources/README.md index 8742a9512..aae1f62d5 100644 --- a/docs/eventing/sources/README.md +++ b/docs/eventing/sources/README.md @@ -2,7 +2,7 @@ This is a generated file and should not be changed manually. All changes should follow the procedure: -1. Update the information in [`sources.yaml`](sources.yaml). +1. Update the information in [`sources.yaml`](./sources.yaml). 2. Run the generator tool: ```shell @@ -10,47 +10,40 @@ procedure: ``` --> -# Knative Event Sources - -Event Sources are Kubernetes Custom Resources which provide a mechanism for registering interest in -a class of events from a particular software system. Since different event sources may be described -by different Custom Resources, this page provides an index of the available source resource types as -well as links to installation instructions. +Event Sources are Kubernetes Custom Resources which provide a mechanism for +registering interest in a class of events from a particular software system. +Since different event sources may be described by different Custom Resources, +this page provides an index of the available source resource types as well as +links to installation instructions. This is a non-exhaustive list of Event sources for Knative. - ### Inclusion in this list is not an endorsement, nor does it imply any level of support. - ## Sources These are sources that are installed as `CRD`s. -Name | Status | Support | Description ---- | --- | --- | --- -[AWS SQS](https://github.com/knative/eventing-sources/blob/master/pkg/apis/sources/v1alpha1/aws_sqs_types.go) | Proof of Concept | None | Brings [AWS Simple Quele Service](https://aws.amazon.com/sqs/) messages into Knative. -[Cron Job](https://github.com/knative/eventing-sources/blob/master/pkg/apis/sources/v1alpha1/cron_job_types.go) | Proof of Concept | None | Uses an in-memory timer to produce events on the specified Cron schedule. -[GCP PubSub](https://github.com/knative/eventing-sources/blob/master/contrib/gcppubsub/pkg/apis/sources/v1alpha1/gcp_pubsub_types.go) | Proof of Concept | None | Brings [GCP PubSub](https://cloud.google.com/pubsub/) messages into Knative. -[GitHub](https://github.com/knative/eventing-sources/blob/master/pkg/apis/sources/v1alpha1/githubsource_types.go) | Proof of Concept | None | Registers for events of the specified types on the specified GitHub organization/repository. Brings those events into Knative. -[GitLab](https://gitlab.com/triggermesh/gitlabsource) | Proof of Concept | None | Registers for events of the specified types on the specified GitLab repository. Brings those events into Knative. -[Google Cloud Scheduler](https://github.com/vaikas-google/csr) | Active Development | None | Create, update, and delete [Google Cloud Scheduler](https://cloud.google.com/scheduler/) Jobs. When those jobs are triggered, receive the event inside Knative. -[Google Cloud Storage](https://github.com/vaikas-google/gcs) | Active Development | None | Registers for events of the specified types on the specified Google Cloud Storage bucket and optional object prefix. Brings those events into Knative. -[Kubernetes](https://github.com/knative/eventing-sources/blob/master/pkg/apis/sources/v1alpha1/kuberneteseventsource_types.go) | Active Development | Knative | Brings Kubernetes cluster events into Knative. Uses ContainerSource for underlying infrastructure. - - +| Name | Status | Support | Description | +| ------------------------------------------------------------------------------------------------------------------------------------- | ------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [AWS SQS](https://github.com/knative/eventing-sources/blob/master/pkg/apis/sources/v1alpha1/aws_sqs_types.go) | Proof of Concept | None | Brings [AWS Simple Quele Service](https://aws.amazon.com/sqs/) messages into Knative. | +| [Cron Job](https://github.com/knative/eventing-sources/blob/master/pkg/apis/sources/v1alpha1/cron_job_types.go) | Proof of Concept | None | Uses an in-memory timer to produce events on the specified Cron schedule. | +| [GCP PubSub](https://github.com/knative/eventing-sources/blob/master/contrib/gcppubsub/pkg/apis/sources/v1alpha1/gcp_pubsub_types.go) | Proof of Concept | None | Brings [GCP PubSub](https://cloud.google.com/pubsub/) messages into Knative. | +| [GitHub](https://github.com/knative/eventing-sources/blob/master/pkg/apis/sources/v1alpha1/githubsource_types.go) | Proof of Concept | None | Registers for events of the specified types on the specified GitHub organization/repository. Brings those events into Knative. | +| [GitLab](https://gitlab.com/triggermesh/gitlabsource) | Proof of Concept | None | Registers for events of the specified types on the specified GitLab repository. Brings those events into Knative. | +| [Google Cloud Scheduler](https://github.com/vaikas-google/csr) | Active Development | None | Create, update, and delete [Google Cloud Scheduler](https://cloud.google.com/scheduler/) Jobs. When those jobs are triggered, receive the event inside Knative. | +| [Google Cloud Storage](https://github.com/vaikas-google/gcs) | Active Development | None | Registers for events of the specified types on the specified Google Cloud Storage bucket and optional object prefix. Brings those events into Knative. | +| [Kubernetes](https://github.com/knative/eventing-sources/blob/master/pkg/apis/sources/v1alpha1/kuberneteseventsource_types.go) | Active Development | Knative | Brings Kubernetes cluster events into Knative. Uses ContainerSource for underlying infrastructure. | ## Meta Sources These are not directly usable, but make writing a Source much easier. -Name | Status | Support | Description ---- | --- | --- | --- -[Auto Container Source](https://github.com/Harwayne/auto-container-source) | Proof of Concept | None | AutoContainerSource is a controller that allows the Source CRDs _without_ needing a controller. It notices CRDs with a specific label and starts controlling resources of that type. It utilizes Container Source as underlying infrastructure. -[Container Source](https://github.com/knative/eventing-sources/blob/master/pkg/apis/sources/v1alpha1/containersource_types.go) | Active Development | Knative | Container Source is a generic controller. Given an Image URL, it will keep a single `Pod` running with the specified image, environment, and arguments. It is used by multiple other Sources as underlying infrastructure. -[Sample Source](https://github.com/grantr/sample-source) | Proof of Concept | None | SampleSource is a reference implementation supporting the [Writing an Event Source the Hard Way tutorial](../samples/writing-a-source). - - +| Name | Status | Support | Description | +| ------------------------------------------------------------------------------------------------------------------------------ | ------------------ | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| [Auto Container Source](https://github.com/Harwayne/auto-container-source) | Proof of Concept | None | AutoContainerSource is a controller that allows the Source CRDs _without_ needing a controller. It notices CRDs with a specific label and starts controlling resources of that type. It utilizes Container Source as underlying infrastructure. | +| [Container Source](https://github.com/knative/eventing-sources/blob/master/pkg/apis/sources/v1alpha1/containersource_types.go) | Active Development | Knative | Container Source is a generic controller. Given an Image URL, it will keep a single `Pod` running with the specified image, environment, and arguments. It is used by multiple other Sources as underlying infrastructure. | +| [Sample Source](https://github.com/grantr/sample-source) | Proof of Concept | None | SampleSource is a reference implementation supporting the [Writing an Event Source the Hard Way tutorial](../samples/writing-a-source). | ### ContainerSource Containers diff --git a/docs/eventing/sources/_index.md b/docs/eventing/sources/_index.md new file mode 100644 index 000000000..d93a8691c --- /dev/null +++ b/docs/eventing/sources/_index.md @@ -0,0 +1,8 @@ +--- +title: "Knative Eventing sources" +linkTitle: "Eventing sources" +weight: 20 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/eventing/sources/generator/ReadmeTemplate.gomd b/docs/eventing/sources/generator/ReadmeTemplate.gomd index f4efeb12e..dadc2838a 100644 --- a/docs/eventing/sources/generator/ReadmeTemplate.gomd +++ b/docs/eventing/sources/generator/ReadmeTemplate.gomd @@ -13,8 +13,6 @@ procedure: ``` --> -# Knative Event Sources - Event Sources are Kubernetes Custom Resources which provide a mechanism for registering interest in a class of events from a particular software system. Since different event sources may be described by different Custom Resources, this page provides an index of the available source resource types as diff --git a/docs/install/Knative-custom-install.md b/docs/install/Knative-custom-install.md index 00a62a1d7..e14adc520 100644 --- a/docs/install/Knative-custom-install.md +++ b/docs/install/Knative-custom-install.md @@ -1,4 +1,8 @@ -# Performing a Custom Knative Installation +--- +title: "Performing a Custom Knative Installation" +linkTitle: "Custom Install" +weight: 10 +--- Use this guide to perform a custom installation of Knative on an existing Kubernetes cluster. Knative's pluggable components allow you to install only @@ -32,7 +36,7 @@ to run multiple installation commands. > Note: [Gloo](https://gloo.solo.io/) is available as an alternative to Istio. > Gloo is not currently compatible with the Knative Eventing component. -> [Click here](Knative-with-Gloo.md) to install Knative with Gloo. +> [Click here](./Knative-with-Gloo.md) to install Knative with Gloo. Knative depends on [Istio](https://istio.io/docs/concepts/what-is-istio/) for traffic routing and ingress. You have the option of injecting Istio sidecars and @@ -204,8 +208,8 @@ files from the Knative repositories: | [`in-memory-channel.yaml`][4.3] | Installs only the in-memory channel provisioner. | Serving component, Eventing component | | [`kafka.yaml`][4.4] | Installs only the Kafka channel provisioner. | Serving component, Eventing component | | **knative/eventing-sources** | | | -| [`release.yaml`][5.1]† | Installs the following sources: [Kubernetes][6], [GitHub][6.1], [Container image][6.2], [CronJob][6.3] | Serving component, Eventing component | -| [`gcppubsub.yaml`][5.2] | Installs the following sources: [PubSub][6.4] | Serving component, Eventing component | +| [`release.yaml`][5.1]† | Installs the following sources: [Kubernetes][6], [GitHub][6.1], [Container image][../eventing#containersource], [CronJob][6.2] | Serving component, Eventing component | +| [`release-gcppubsub.yaml`][5.2] | Installs the following sources: [PubSub][6.3] | Serving component, Eventing component | | [`message-dumper.yaml`][5.3] | Installs an Event logging service for debugging. | Serving component, Eventing component | | **Cluster roles** | | | | [`clusterrole.yaml`][7]† | Enables the Build and Serving components to interact. | Serving component, Build component | @@ -216,6 +220,7 @@ for details about installing the various supported observability plug-ins. † These are the recommended standard install files suitable for most use cases. + [1]: https://github.com/knative/serving/releases/tag/v0.4.0 [1.1]: https://github.com/knative/serving/releases/download/v0.4.0/serving.yaml [1.2]: @@ -253,10 +258,9 @@ for details about installing the various supported observability plug-ins. [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.2]: https://github.com/knative/docs/tree/master/eventing#containersource -[6.3]: +[6.2]: https://github.com/knative/eventing-sources/blob/master/samples/cronjob-source/README.md -[6.4]: https://cloud.google.com/pubsub/ +[6.3]: https://cloud.google.com/pubsub/ [7]: https://raw.githubusercontent.com/knative/serving/v0.4.0/third_party/config/build/clusterrole.yaml ### Installing Knative @@ -365,4 +369,12 @@ guides to help you get started with Knative: - [Knative Eventing overview](../eventing/README.md) - - [Knative Eventing code samples](../eventing/samples) + - [Knative Eventing code samples](../eventing/samples/) + +--- + +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). + diff --git a/docs/install/Knative-with-AKS.md b/docs/install/Knative-with-AKS.md index e17d1abed..94422ba01 100644 --- a/docs/install/Knative-with-AKS.md +++ b/docs/install/Knative-with-AKS.md @@ -1,9 +1,13 @@ -# Knative Install on Azure Kubernetes Service (AKS) +--- +title: "Install on Azure Kubernetes Service (AKS)" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 15 +--- This guide walks you through the installation of the latest version of Knative using pre-built images. -You can find [guides for other platforms here](README.md). +You can find [guides for other platforms here](./README.md). ## Before you begin @@ -130,7 +134,7 @@ recommended configuration for a cluster is: > Note: [Gloo](https://gloo.solo.io/) is available as an alternative to Istio. > Gloo is not currently compatible with the Knative Eventing component. -> [Click here](Knative-with-Gloo.md) to install Knative with Gloo. +> [Click here](./Knative-with-Gloo.md) to install Knative with Gloo. Knative depends on Istio. @@ -166,7 +170,7 @@ rerun the command to see the current status. The following commands install all available Knative components. To customize your Knative installation, see -[Performing a Custom Knative Installation](Knative-custom-install.md). +[Performing a Custom Knative Installation](./Knative-custom-install.md). 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 @@ -204,7 +208,7 @@ Now that your cluster has Knative installed, you can see what Knative has to offer. To deploy your first app with Knative, follow the step-by-step -[Getting Started with Knative App Deployment](getting-started-knative-app.md) +[Getting Started with Knative App Deployment](./getting-started-knative-app.md) guide. To get started with Knative Eventing, pick one of the diff --git a/docs/install/Knative-with-Docker-for-Mac.md b/docs/install/Knative-with-Docker-for-Mac.md index 2945a35a3..7e982e0a3 100644 --- a/docs/install/Knative-with-Docker-for-Mac.md +++ b/docs/install/Knative-with-Docker-for-Mac.md @@ -1,11 +1,15 @@ -# Knative Install on Docker for Mac +--- +title: "Install on Docker for Mac" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 15 +--- This guide walks you through the installation of the latest version of [Knative Serving](https://github.com/knative/serving) using pre-built images and demonstrates creating and deploying an image of a sample "hello world" app onto the newly created Knative cluster. -You can find [guides for other platforms here](README.md). +You can find [guides for other platforms here](./README.md). ## Before you begin @@ -95,7 +99,7 @@ Now that your cluster has Knative installed, you're ready to deploy an app. If you'd like to follow a step-by-step guide for deploying your first app on Knative, check out the -[Getting Started with Knative App Deployment](getting-started-knative-app.md) +[Getting Started with Knative App Deployment](./getting-started-knative-app.md) guide. If you'd like to view the available sample apps and deploy one of your choosing, diff --git a/docs/install/Knative-with-GKE.md b/docs/install/Knative-with-GKE.md index 1886a90be..8f13fcbc1 100644 --- a/docs/install/Knative-with-GKE.md +++ b/docs/install/Knative-with-GKE.md @@ -1,9 +1,13 @@ -# Knative Install on Google Kubernetes Engine +--- +title: "Install on Google Kubernetes Engine" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 15 +--- This guide walks you through the installation of the latest version of all Knative components using pre-built images. -You can find [guides for other platforms here](README.md). +You can find [guides for other platforms here](./README.md). ## Before you begin @@ -130,7 +134,7 @@ Admin permissions are required to create the necessary > Note: [Gloo](https://gloo.solo.io/) is available as an alternative to Istio. > Gloo is not currently compatible with the Knative Eventing component. -> [Click here](Knative-with-Gloo.md) to install Knative with Gloo. +> [Click here](./Knative-with-Gloo.md) to install Knative with Gloo. Knative depends on Istio. @@ -167,7 +171,7 @@ rerun the command to see the current status. The following commands install all available Knative components as well as the standard set of observability plugins. To customize your Knative installation, -see [Performing a Custom Knative Installation](Knative-custom-install.md). +see [Performing a Custom Knative Installation](./Knative-custom-install.md). 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 @@ -206,7 +210,7 @@ Now that your cluster has Knative installed, you can see what Knative has to offer. To deploy your first app with Knative, follow the step-by-step -[Getting Started with Knative App Deployment](getting-started-knative-app.md) +[Getting Started with Knative App Deployment](./getting-started-knative-app.md) guide. To get started with Knative Eventing, pick one of the diff --git a/docs/install/Knative-with-Gardener.md b/docs/install/Knative-with-Gardener.md index 0ee433356..7fd7cbba2 100644 --- a/docs/install/Knative-with-Gardener.md +++ b/docs/install/Knative-with-Gardener.md @@ -1,4 +1,8 @@ -# Knative Install on [Gardener](https://github.com/gardener) +--- +title: "Install on Gardener" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 10 +--- This guide walks you through the installation of the latest version of Knative using pre-built images on a [Gardener](https://gardener.cloud) created cluster @@ -9,7 +13,7 @@ or have a look at the project. To learn more about this open source project, read the [blog on kubernetes.io](https://kubernetes.io/blog/2018/05/17/gardener/). -You can find [guides for other platforms here](README.md). +You can find [guides for other platforms here](./README.md). ## Before you begin @@ -35,7 +39,7 @@ Knative requires a Kubernetes cluster v1.11 or newer. your project. You can skip this step if you create your cluster using the user interface; it is only needed for programmatic access, make sure you set `export KUBECONFIG=garden-my-project.yaml` in your shell. - ![Download kubeconfig for Gardener](images/gardener_service_account.png "downloading the kubeconfig using a service account") + ![Download kubeconfig for Gardener](../images/gardener_service_account.png "downloading the kubeconfig using a service account") ### Creating a Kubernetes cluster @@ -51,7 +55,7 @@ kubectl apply --filename my-cluster.yaml The easier alternative is to create the cluster following the cluster creation wizard in the Gardener dashboard: -![shoot creation](images/gardener_shoot_creation.png "shoot creation via the dashboard") +![shoot creation](../images/gardener_shoot_creation.png "shoot creation via the dashboard") ### Configure kubectl for your cluster @@ -102,7 +106,7 @@ rerun the command to see the current status. The following commands install all available Knative components as well as the standard set of observability plugins. To customize your Knative installation, -see [Performing a Custom Knative Installation](Knative-custom-install.md). +see [Performing a Custom Knative Installation](./Knative-custom-install.md). 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 @@ -171,7 +175,7 @@ Now that your cluster has Knative installed, you can see what Knative has to offer. To deploy your first app with Knative, follow the step-by-step -[Getting Started with Knative App Deployment](getting-started-knative-app.md) +[Getting Started with Knative App Deployment](./getting-started-knative-app.md) guide. To get started with Knative Eventing, pick one of the diff --git a/docs/install/Knative-with-Gloo.md b/docs/install/Knative-with-Gloo.md index 80d57dfe9..c1c14a380 100644 --- a/docs/install/Knative-with-Gloo.md +++ b/docs/install/Knative-with-Gloo.md @@ -1,4 +1,8 @@ -# Knative Install using Gloo on a Kubernetes Cluster +--- +title: "Knative Install using Gloo on a Kubernetes Cluster" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 10 +--- This guide walks you through the installation of the latest version of Knative using pre-built images. @@ -70,7 +74,7 @@ Now that your cluster has Knative installed, you can see what Knative has to offer. To deploy your first app with Knative, follow the step-by-step -[Getting Started with Knative App Deployment](getting-started-knative-app.md) +[Getting Started with Knative App Deployment](./getting-started-knative-app.md) guide. Note that when you've finished deploying the app, you'll need to connect to the @@ -94,7 +98,7 @@ curl -H "Host: helloworld-go.myproject.example.com" $GATEWAY_URL ``` The full instructions for the -[Go Hello-World Sample](../serving/samples/helloworld-go) with this substitution +[Go Hello-World Sample](../serving/samples/hello-world/helloworld-go) with this substitution are published bellow: ### Deploy the Hello-World Go App: @@ -261,4 +265,4 @@ kubectl delete --filename service.yaml ``` Great! our Knative ingress is up and running. See -https://github.com/knative/docs for more information on using Knative. +[Knative documentation](../README.md) for more information on using Knative. diff --git a/docs/install/Knative-with-ICP.md b/docs/install/Knative-with-ICP.md index bac808dac..160aa0e2d 100644 --- a/docs/install/Knative-with-ICP.md +++ b/docs/install/Knative-with-ICP.md @@ -1,4 +1,8 @@ -# Knative Install on IBM Cloud Private +--- +title: "Install on IBM Cloud Private" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 15 +--- This guide walks you through the installation of the latest version of [Knative Serving](https://github.com/knative/serving) and @@ -7,7 +11,7 @@ demonstrates creating and deploying an image of a sample `hello world` app onto the newly created Knative cluster on [IBM Cloud Private](https://www.ibm.com/cloud/private). -You can find [guides for other platforms here](README.md). +You can find [guides for other platforms here](./README.md). ## Before you begin @@ -124,7 +128,7 @@ the`knative-build` and `knative-monitoring` namespaces. The following commands install all available Knative components as well as the standard set of observability plugins. To customize your Knative installation, -see [Performing a Custom Knative Installation](Knative-custom-install.md). +see [Performing a Custom Knative Installation](./Knative-custom-install.md). 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 @@ -202,7 +206,7 @@ Now that your cluster has Knative installed, you can see what Knative has to offer. To deploy your first app with Knative, follow the step-by-step -[Getting Started with Knative App Deployment](getting-started-knative-app.md) +[Getting Started with Knative App Deployment](./getting-started-knative-app.md) guide. > **Note**: When looking up the IP address to use for accessing your app, you diff --git a/docs/install/Knative-with-IKS.md b/docs/install/Knative-with-IKS.md index 2feac254b..bae7546d7 100644 --- a/docs/install/Knative-with-IKS.md +++ b/docs/install/Knative-with-IKS.md @@ -1,15 +1,19 @@ -# Knative Install on IBM Cloud Kubernetes Service (IKS) +--- +title: "Install on IBM Cloud Kubernetes Service (IKS)" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 10 +--- This guide walks you through the installation of the latest version of Knative using pre-built images. -You may also have it all installed for you by clicking the button below: +You may also have it all installed for you by clicking the button below: [![Deploy to IBM Cloud](https://bluemix.net/deploy/button_x2.png)](https://console.bluemix.net/devops/setup/deploy?repository=https://git.ng.bluemix.net/start-with-knative/toolchain.git) More [instructions on the deploy button here](https://git.ng.bluemix.net/start-with-knative/toolchain/blob/master/README.md). -You can find [guides for other platforms here](README.md). +You can find [guides for other platforms here](./README.md). ## Before you begin @@ -163,7 +167,7 @@ rerun the command to see the current status. The following commands install all available Knative components as well as the standard set of observability plugins. To customize your Knative installation, -see [Performing a Custom Knative Installation](Knative-custom-install.md). +see [Performing a Custom Knative Installation](./Knative-custom-install.md). 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 @@ -201,7 +205,7 @@ Now that your cluster has Knative installed, you can see what Knative has to offer. To deploy your first app with Knative, follow the step-by-step -[Getting Started with Knative App Deployment](getting-started-knative-app.md) +[Getting Started with Knative App Deployment](./getting-started-knative-app.md) guide. To get started with Knative Eventing, pick one of the diff --git a/docs/install/Knative-with-Minikube.md b/docs/install/Knative-with-Minikube.md index dcf200968..25b564192 100644 --- a/docs/install/Knative-with-Minikube.md +++ b/docs/install/Knative-with-Minikube.md @@ -1,11 +1,15 @@ -# Knative Install on Minikube +--- +title: "Install on Minikube" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 10 +--- This guide walks you through the installation of the latest version of [Knative Serving](https://github.com/knative/serving) using pre-built images and demonstrates creating and deploying an image of a sample "hello world" app onto the newly created Knative cluster. -You can find [guides for other platforms here](README.md). +You can find [guides for other platforms here](./README.md). ## Before you begin @@ -55,7 +59,7 @@ minikube start --memory=8192 --cpus=4 \ > Note: [Gloo](https://gloo.solo.io/) is available as an alternative to Istio. > Gloo is not currently compatible with the Knative Eventing component. -> [Click here](Knative-with-Gloo.md) to install Knative with Gloo. +> [Click here](./Knative-with-Gloo.md) to install Knative with Gloo. Knative depends on Istio. Run the following to install Istio. (We are changing `LoadBalancer` to `NodePort` for the `istio-ingress` service). @@ -133,7 +137,7 @@ Now that your cluster has Knative installed, you're ready to deploy an app. If you'd like to follow a step-by-step guide for deploying your first app on Knative, check out the -[Getting Started with Knative App Deployment](getting-started-knative-app.md) +[Getting Started with Knative App Deployment](./getting-started-knative-app.md) guide. If you'd like to view the available sample apps and deploy one of your choosing, diff --git a/docs/install/Knative-with-Minishift.md b/docs/install/Knative-with-Minishift.md index e38caf0d6..958eba3c2 100644 --- a/docs/install/Knative-with-Minishift.md +++ b/docs/install/Knative-with-Minishift.md @@ -1,4 +1,8 @@ -# Knative Install on Minishift +--- +title: "Install on Minishift" +linkTitle: "Minishift" +weight: 10 +--- This guide walks you through the installation of the latest version of [Knative Serving](https://github.com/knative/serving) on an @@ -6,11 +10,11 @@ This guide walks you through the installation of the latest version of demonstrates creating and deploying an image of a sample "hello world" app onto the newly created Knative cluster. -You can find [guides for other platforms here](README.md). +You can find [guides for other platforms here](./README.md). ## Minishift setup -- Setup minishift based instructions from +- Set up minishift based instructions from https://docs.okd.io/latest/minishift/getting-started/index.html - Ensure `minishift` is setup correctly by running the command: @@ -149,13 +153,13 @@ until oc login -u admin -p admin; do sleep 5; done; ### Installing Istio Knative depends on Istio. The -[istio-openshift-policies.sh](scripts/istio-openshift-policies.sh) does run the +[istio-openshift-policies.sh](./scripts/istio-openshift-policies.sh) does run the required commands to configure necessary [privileges](https://istio.io/docs/setup/kubernetes/platform-setup/openshift/) to the service accounts used by Istio. ```shell -curl -s https://raw.githubusercontent.com/knative/docs/master/install/scripts/istio-openshift-policies.sh | bash +curl -s https://raw.githubusercontent.com/knative/docs/master/docs/install/scripts/istio-openshift-policies.sh | bash ``` 1. Run the following to install Istio: @@ -185,12 +189,12 @@ curl -s https://raw.githubusercontent.com/knative/docs/master/install/scripts/is The following section details on deploying [Knative Serving](https://github.com/knative/serving) to OpenShift. -The [knative-openshift-policies.sh](scripts/knative-openshift-policies.sh) runs +The [knative-openshift-policies.sh](./scripts/knative-openshift-policies.sh) runs the required commands to configure necessary privileges to the service accounts used by Knative. ```shell -curl -s https://raw.githubusercontent.com/knative/docs/master/install/scripts/knative-openshift-policies.sh | bash +curl -s https://raw.githubusercontent.com/knative/docs/master/docs/install/scripts/knative-openshift-policies.sh | bash ``` > You can safely ignore the warnings: diff --git a/docs/install/Knative-with-OpenShift.md b/docs/install/Knative-with-OpenShift.md index ead7a1db4..adf264ca2 100644 --- a/docs/install/Knative-with-OpenShift.md +++ b/docs/install/Knative-with-OpenShift.md @@ -1,4 +1,8 @@ -# Knative Install on OpenShift (via `oc cluster up`) +--- +title: "Install on OpenShift" +linkTitle: "OpenShift" +weight: 15 +--- This guide walks you through the installation of the latest version of [Knative Serving](https://github.com/knative/serving) on an @@ -6,7 +10,7 @@ This guide walks you through the installation of the latest version of demonstrates creating and deploying an image of a sample "hello world" app onto the newly created Knative cluster. -You can find [guides for other platforms here](README.md). +You can find [guides for other platforms here](./README.md). ## Before you begin @@ -23,7 +27,7 @@ directory by downloading the right release tarball for your OS from the ```shell wget https://github.com/openshift/origin/releases/download/v3.11.0/openshift-origin-client-tools-v3.11.0-0cbc58b-linux-64bit.tar.gz -o oc.tar.gz -tar xzvf openshift*tar.gz +tar xzvf openshift*tar.gz mv openshift-origin-client-tools-*/oc . mv openshift-origin-client-tools-*/kubectl . rm -rf openshift-origin-client-tools-*/ @@ -33,9 +37,12 @@ You will now have the `oc` (and `kubectl`) binaries in your local directory. ## Scripted cluster setup and installation -For Linux and Mac, once you have `oc` present on your machine and in your `PATH`, you can run a -[script](scripts/knative-with-openshift.sh) that automates the steps on this -page. It will: +For Linux and Mac, you can optionally run a +[script](./scripts/knative-with-openshift.sh) that automates the steps on this +page. + +Once you have `oc` present on your machine and in your `PATH`, you can simply +run [this script](./scripts/knative-with-openshift.sh); it will: - Create a new OpenShift cluster on your local machine with `oc cluster up` - Install Istio and Knative serving @@ -98,7 +105,7 @@ oc label namespace default istio-injection=enabled > Note: [Gloo](https://gloo.solo.io/) is available as an alternative to Istio. > Gloo is not currently compatible with the Knative Eventing component. -> [Click here](Knative-with-Gloo.md) to install Knative with Gloo. +> [Click here](./Knative-with-Gloo.md) to install Knative with Gloo. Knative depends on Istio. First, run the following to grant the necessary privileges to the service accounts istio will use: @@ -210,7 +217,7 @@ Now that your cluster has Knative installed, you're ready to deploy an app. If you'd like to follow a step-by-step guide for deploying your first app on Knative, check out the -[Getting Started with Knative App Deployment](getting-started-knative-app.md) +[Getting Started with Knative App Deployment](./getting-started-knative-app.md) guide. If you'd like to view the available sample apps and deploy one of your choosing, diff --git a/docs/install/Knative-with-PKS.md b/docs/install/Knative-with-PKS.md index f8e17f7c9..ee1590b93 100644 --- a/docs/install/Knative-with-PKS.md +++ b/docs/install/Knative-with-PKS.md @@ -1,9 +1,13 @@ -# Knative Install on Pivotal Container Service +--- +title: "Install on Pivotal Container Service" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 10 +--- This guide walks you through the installation of the latest version of Knative using pre-built images. -You can find [guides for other platforms here](README.md). +You can find [guides for other platforms here](./README.md). ## Before you begin @@ -76,7 +80,7 @@ rerun the command to see the current status. The following commands install all available Knative components as well as the standard set of observability plugins. To customize your Knative installation, -see [Performing a Custom Knative Installation](Knative-custom-install.md). +see [Performing a Custom Knative Installation](./Knative-custom-install.md). 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 @@ -114,7 +118,7 @@ Now that your cluster has Knative installed, you can see what Knative has to offer. To deploy your first app with Knative, follow the step-by-step -[Getting Started with Knative App Deployment](getting-started-knative-app.md) +[Getting Started with Knative App Deployment](./getting-started-knative-app.md) guide. To get started with Knative Eventing, pick one of the diff --git a/docs/install/Knative-with-any-k8s.md b/docs/install/Knative-with-any-k8s.md index 44963b82f..d70997aac 100644 --- a/docs/install/Knative-with-any-k8s.md +++ b/docs/install/Knative-with-any-k8s.md @@ -1,4 +1,8 @@ -# Knative Install on a Kubernetes Cluster +--- +title: "Install on a Kubernetes cluster" +linkTitle: "On existing cluster" +weight: 15 +--- This guide walks you through the installation of the latest version of Knative using pre-built images. @@ -32,11 +36,13 @@ Containers. about an unknown type, run the second `kubectl apply` command again. 1. Label the default namespace with `istio-injection=enabled`: + ```bash kubectl label namespace default istio-injection=enabled ``` 1. Monitor the Istio components until all of the components show a `STATUS` of `Running` or `Completed`: + ```bash kubectl get pods --namespace istio-system ``` @@ -52,18 +58,20 @@ rerun the command to see the current status. The following commands install all available Knative components. To customize your Knative installation, see -[Performing a Custom Knative Installation](Knative-custom-install.md). +[Performing a Custom Knative Installation](./Knative-custom-install.md). 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: - ``` + + ```bash kubectl delete svc knative-ingressgateway -n istio-system kubectl delete deploy knative-ingressgateway -n istio-system ``` 1. Run the `kubectl apply` command to install Knative and its dependencies: + ```bash kubectl apply --filename https://github.com/knative/serving/releases/download/v0.4.0/serving.yaml \ --filename https://github.com/knative/build/releases/download/v0.4.0/build.yaml \ @@ -72,11 +80,13 @@ your Knative installation, see --filename https://github.com/knative/serving/releases/download/v0.4.0/monitoring.yaml \ --filename https://raw.githubusercontent.com/knative/serving/v0.4.0/third_party/config/build/clusterrole.yaml ``` + > **Note**: For the v0.4.0 release and newer, the `clusterrole.yaml` file is > required to enable the Build and Serving components to interact with each other. 1. Monitor the Knative components until all of the components show a `STATUS` of `Running`: + ```bash kubectl get pods --namespace knative-serving kubectl get pods --namespace knative-build @@ -91,7 +101,7 @@ Now that your cluster has Knative installed, you can see what Knative has to offer. To deploy your first app with Knative, follow the step-by-step -[Getting Started with Knative App Deployment](getting-started-knative-app.md) +[Getting Started with Knative App Deployment](./getting-started-knative-app.md) guide. To get started with Knative Eventing, pick one of the @@ -99,3 +109,10 @@ To get started with Knative Eventing, pick one of the To get started with Knative Build, read the [Build README](../build/README.md), then choose a sample to walk through. + +--- + +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). diff --git a/docs/install/README.md b/docs/install/README.md index c057a1af6..1fad29f6c 100644 --- a/docs/install/README.md +++ b/docs/install/README.md @@ -1,4 +1,3 @@ -# Installing Knative Follow this guide to install Knative components on a platform of your choice. @@ -29,7 +28,7 @@ Currently, two options exist which provide this functionality: ## Installing Knative with Gloo -[Install with Gloo](Knative-with-Gloo.md): Gloo functions as a lightweight +[Install with Gloo](./Knative-with-Gloo.md): Gloo functions as a lightweight gateway for Knative. Choose this option if you don't require service mesh in your cluster and want a lighter-weight alternative to Istio. Note that _the Knative Eventing component_ is not supported by Gloo at this time. @@ -66,39 +65,39 @@ The guides below show you how to create a Kubernetes cluster with the right specs for Knative on your platform of choice, then walk through installing all available Knative components and a set of observability plugins. -- [Knative Install on Azure Kubernetes Service](Knative-with-AKS.md) -- [Knative Install on Gardener](Knative-with-Gardener.md) -- [Knative Install on Google Kubernetes Engine](Knative-with-GKE.md) -- [Knative Install on IBM Cloud Kubernetes Service](Knative-with-IKS.md) -- [Knative Install on IBM Cloud Private](Knative-with-ICP.md) -- [Knative Install on Pivotal Container Service](Knative-with-PKS.md) +- [Knative Install on Azure Kubernetes Service](./Knative-with-AKS.md) +- [Knative Install on Gardener](./Knative-with-Gardener.md) +- [Knative Install on Google Kubernetes Engine](./Knative-with-GKE.md) +- [Knative Install on IBM Cloud Kubernetes Service](./Knative-with-IKS.md) +- [Knative Install on IBM Cloud Private](./Knative-with-ICP.md) +- [Knative Install on Pivotal Container Service](./Knative-with-PKS.md) If you already have a Kubernetes cluster you're comfortable installing _alpha_ software on, use the following guide to install all Knative components: -- [Knative Install on any Kubernetes](Knative-with-any-k8s.md) +- [Knative Install on any Kubernetes](./Knative-with-any-k8s.md) **Limited install guides** The guides below install some of the available Knative components, without all available observability plugins, to minimize the disk space used for install. -- [Knative Install on Docker for Mac](Knative-with-Docker-for-Mac.md) -- [Knative Install on Minikube](Knative-with-Minikube.md) -- [Knative Install on OpenShift (minishift)](Knative-with-Minishift.md) -- [Knative Install on OpenShift (oc cluster up)](Knative-with-OpenShift.md) +- [Knative Install on Docker for Mac](./Knative-with-Docker-for-Mac.md) +- [Knative Install on Minikube](./Knative-with-Minikube.md) +- [Knative Install on Minishift](./Knative-with-Minishift.md) +- [Knative Install on OpenShift](./Knative-with-OpenShift.md) **Custom install guide** To choose which components and observability plugins to install, follow the custom install guide: -- [Perfoming a Custom Knative Installation](Knative-custom-install.md) +- [Performing a Custom Knative Installation](./Knative-custom-install.md) > **Note**: If need to set up a Kubernetes cluster with the correct > specifications to run Knative, you can follow any of the install instructions > through the creation of the cluster, then follow the -> [Perfoming a Custom Knative Installation](knative-custom-install.md) guide. +> [Performing a Custom Knative Installation](./knative-custom-install.md) guide. **Observability install guide** @@ -112,7 +111,7 @@ Knative cluster. Now you're ready to deploy an app: - Follow the step-by-step - [Getting Started with Knative App Deployment](getting-started-knative-app.md) + [Getting Started with Knative App Deployment](./getting-started-knative-app.md) guide. - View the available [sample apps](../serving/samples) and deploy one of your @@ -134,7 +133,7 @@ and set up an Istio IP range for outbound network access: ## Checking the version of your Knative Serving installation -- [Checking the version of your Knative Serving installation](check-install-version.md) +- [Checking the version of your Knative Serving installation](./check-install-version.md) --- diff --git a/docs/install/_index.md b/docs/install/_index.md new file mode 100644 index 000000000..109f1bca7 --- /dev/null +++ b/docs/install/_index.md @@ -0,0 +1,8 @@ +--- +title: "Installing Knative" +#linkTitle: "Installing" +weight: 20 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/install/check-install-version.md b/docs/install/check-install-version.md index c74b032b1..ae0017f77 100644 --- a/docs/install/check-install-version.md +++ b/docs/install/check-install-version.md @@ -1,4 +1,8 @@ -# Checking the Version of Your Knative Serving Installation +--- +title: "Checking the Version of Your Knative Serving Installation" +#linkTitle: "Checking your install version" +weight: 20 +--- If you want to check what version of Knative serving you have installed, enter the following command: @@ -33,4 +37,4 @@ classification," and in that section is a list of tags. The versions of Knative you have installed will appear in the list as `v0.1.1`, or whatever verion you have installed: -![Shows list of tags on container details page; v0.1.1 is the Knative version and is the first tag.](../images/knative-version.png) +![Shows list of tags on container details page; v0.1.1 is the Knative version and is the first tag.](../../images/knative-version.png) diff --git a/docs/install/getting-started-knative-app.md b/docs/install/getting-started-knative-app.md index fbc8b5385..a3b2c85b7 100644 --- a/docs/install/getting-started-knative-app.md +++ b/docs/install/getting-started-knative-app.md @@ -1,4 +1,8 @@ -# Getting Started with Knative App Deployment +--- +title: "Getting Started with App Deployment" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 05 +--- This guide shows you how to deploy an app using Knative, then interact with it using cURL requests. @@ -15,7 +19,7 @@ You need: ## Sample application This guide uses the -[Hello World sample app in Go](../serving/samples/helloworld-go) to demonstrate +[Hello World sample app in Go](../serving/samples/hello-world/helloworld-go) to demonstrate the basic workflow for deploying an app, but these steps can be adapted for your own application if you have an image of it available on [Docker Hub](https://docs.docker.com/docker-hub/repos/), diff --git a/docs/reference/README.md b/docs/reference/README.md index 21cb236d7..5ef6b7c46 100644 --- a/docs/reference/README.md +++ b/docs/reference/README.md @@ -1,6 +1,114 @@ # Knative API Reference documentation -- [Serving API](serving.md) -- [Build API](build.md) -- [Eventing API](eventing/eventing.md) -- [Event Sources API](eventing/eventing-sources.md) +## View the latest release + +The reference documentation for the latest release of the Knative is available +at [**www.knative.dev**](https://www.knative.dev/docs/reference/). + +### Source files + +The API source files are located at: + +- [Serving API](./serving.md) +- [Build API](./build.md) +- [Eventing API](./eventing/eventing.md) +- [Event Sources API](./eventing/eventing-sources.md) + + +## Updating API Reference docs (for Knative maintainers) + +The Knative API reference documentation is manually generated using the +[`gen-api-reference-docs.sh`](../../hack/) tool. If you need to generate a new +version of the API docs for a recent update or for a new release, you can use +the following steps. + +To learn more about the tool, see the +[gen-crd-api-reference-docs](https://github.com/ahmetb/gen-crd-api-reference-docs) +reference page. + +### Before you begin + +You must meet the following requirements to run the `gen-api-reference-docs.sh` +tool: + +* You need the following software installed: + * [`git`](https://git-scm.com/download/) + * [`go` version 1.11+](https://golang.org/dl/) +* Clone [knative/docs](https://github.com/knative/docs) + locally. For example: `git clone git@github.com:knative/docs.git` + +### Generating the API + +To generate a version of the API: + +1. Ensure that your `GOPATH` is empty. The `gen-api-reference-docs.sh` + script will result in the `GOPATH should not be set` error if your `GOPATH` + is configured. You view the value by running the following command: + + ``` + echo $GOPATH + ``` + + If your `GOPATH` is already configured, temporarily clear the `GOPATH` value + by running the following command: + + ``` + export GOPATH="" + ``` + +1. Locate the commits or tags that correspond to the version of the API + that you want to generate: + + * [Build](https://github.com/knative/build/releases/) + * [Eventing](https://github.com/knative/eventing/releases/) + * [Eventing Sources](https://github.com/knative/eventing-sources/releases/) + * [Serving](https://github.com/knative/serving/releases/) + +1. To run the `gen-api-reference-docs.sh` command from the `hack` directory, + you specify the commits or tags for each of the corresponding Knative + component variables (`KNATIVE_[component_name]_COMMIT`): + + ``` + KNATIVE_BUILD_COMMIT=[commit_or_tag] \ + KNATIVE_EVENTING_COMMIT=[commit_or_tag] \ + KNATIVE_EVENTING_SOURCES_COMMIT=[commit_or_tag] \ + KNATIVE_SERVING_COMMIT=[commit_or_tag] \ + ./gen-api-reference-docs.sh + ``` + + where `[commit_or_tag]` is the commit or tag in the specific repo that + represents the version of the API that you want to generate. Also see + the [example](#example) below. + + **Result** + + The `gen-api-reference-docs.sh` tool generates the API in a `tmp` folder. + After a successful build, the tool automatically opens that folder + in the `tmp` directory. + +1. Copy the generated API files into the `docs/reference` directory of your + knative/docs clone. + +You can now perform the necessary steps to open a PR, complete a review, and +merge the new API files into the appropriate branch of the `knative/docs` repo. +See the [contributor flow](../../contributing/DOCS-CONTRIBUTING.md) for +details about requesting changes in the `knative/docs` repo. + +### Example + +To build a set of Knative API docs for v0.3, you can use the `v0.3.0` the tags +from each of the Knative component repositories, like +[Serving v0.3.0](https://github.com/knative/serving/tree/v0.3.0). If you want to +use a commit for Serving v0.3.0, you would use +[4d198d](https://github.com/knative/serving/commit/4d198db8756db2f8a3c228302a97fb3a216a9475). + +Using tags from each repo, you would run the following command to generate the +v0.3.0 API source files: + +``` +KNATIVE_BUILD_COMMIT=v0.3.0 \ +KNATIVE_EVENTING_COMMIT=v0.3.0 \ +KNATIVE_EVENTING_SOURCES_COMMIT=v0.3.0 \ +KNATIVE_SERVING_COMMIT=v0.3.0 \ +./gen-api-reference-docs.sh +``` diff --git a/docs/reference/_index.md b/docs/reference/_index.md new file mode 100644 index 000000000..5f1ee4b84 --- /dev/null +++ b/docs/reference/_index.md @@ -0,0 +1,8 @@ +--- +title: "Knative Reference Documentation" +linkTitle: "Reference and API" +weight: 100 +type: "docs" +--- + +Knative API and reference documentation. diff --git a/docs/reference/build-api.md b/docs/reference/build-api.md new file mode 100644 index 000000000..ef6b88568 --- /dev/null +++ b/docs/reference/build-api.md @@ -0,0 +1,8 @@ +--- +title: "Knative Build Component" +linkTitle: "Build API" +weight: 20 +type: "docs" +--- + +{{% readfile file="build.md" relative="true" %}} diff --git a/docs/reference/build.md b/docs/reference/build.md index bef66011a..01a1d16f4 100644 --- a/docs/reference/build.md +++ b/docs/reference/build.md @@ -84,10 +84,9 @@ int64 (Optional) -

TODO: Generation does not work correctly with CRD. They are scrubbed -by the APIserver (https://github.com/kubernetes/kubernetes/issues/58778) -So, we add Generation here. Once that gets fixed, remove this and use -ObjectMeta.Generation instead.

+

TODO(dprotaso) Metadata.Generation should increment so we +can drop this property when conversion webhooks enable us +to migrate

@@ -100,11 +99,26 @@ SourceSpec +(Optional)

Source specifies the input to the build.

+sources
+ + +[]SourceSpec + + + + +(Optional) +

Sources specifies the inputs to the build.

+ + + + steps
@@ -113,6 +127,7 @@ SourceSpec +(Optional)

Steps are the steps of the build; each step is run sequentially with the source mounted into /workspace.

@@ -127,6 +142,7 @@ source mounted into /workspace.

+(Optional)

Volumes is a collection of volumes that are available to mount into the steps of the build.

@@ -139,6 +155,7 @@ string +(Optional)

The name of the service account as which to run this build.

@@ -152,6 +169,7 @@ TemplateInstantiationSpec +(Optional)

Template, if specified, references a BuildTemplate resource to use to populate fields in the build, and optional Arguments to pass to the template. The default Kind of template is BuildTemplate

@@ -284,10 +302,9 @@ int64 (Optional) -

TODO: Generation does not work correctly with CRD. They are scrubbed -by the APIserver (https://github.com/kubernetes/kubernetes/issues/58778) -So, we add Generation here. Once that gets fixed, remove this and use -ObjectMeta.Generation instead.

+

TODO(dprotaso) Metadata.Generation should increment so we +can drop this property when conversion webhooks enable us +to migrate

@@ -402,10 +419,9 @@ int64 (Optional) -

TODO: Generation does not work correctly with CRD. They are scrubbed -by the APIserver (https://github.com/kubernetes/kubernetes/issues/58778) -So, we add Generation here. Once that gets fixed, remove this and use -ObjectMeta.Generation instead.

+

TODO(dprotaso) Metadata.Generation should increment so we +can drop this property when conversion webhooks enable us +to migrate

@@ -531,10 +547,9 @@ int64 (Optional) -

TODO: Generation does not work correctly with CRD. They are scrubbed -by the APIserver (https://github.com/kubernetes/kubernetes/issues/58778) -So, we add Generation here. Once that gets fixed, remove this and use -ObjectMeta.Generation instead.

+

TODO(dprotaso) Metadata.Generation should increment so we +can drop this property when conversion webhooks enable us +to migrate

@@ -547,11 +562,26 @@ SourceSpec +(Optional)

Source specifies the input to the build.

+sources
+ + +[]SourceSpec + + + + +(Optional) +

Sources specifies the inputs to the build.

+ + + + steps
@@ -560,6 +590,7 @@ SourceSpec +(Optional)

Steps are the steps of the build; each step is run sequentially with the source mounted into /workspace.

@@ -574,6 +605,7 @@ source mounted into /workspace.

+(Optional)

Volumes is a collection of volumes that are available to mount into the steps of the build.

@@ -586,6 +618,7 @@ string +(Optional)

The name of the service account as which to run this build.

@@ -599,6 +632,7 @@ TemplateInstantiationSpec +(Optional)

Template, if specified, references a BuildTemplate resource to use to populate fields in the build, and optional Arguments to pass to the template. The default Kind of template is BuildTemplate

@@ -677,6 +711,7 @@ BuildProvider +(Optional) @@ -689,6 +724,7 @@ ClusterSpec +(Optional)

Cluster provides additional information if the builder is Cluster.

@@ -702,12 +738,13 @@ GoogleSpec +(Optional)

Google provides additional information if the builder is Google.

-startTime,omitEmpty
+startTime
 Kubernetes meta/v1.Time @@ -715,12 +752,13 @@ Kubernetes meta/v1.Time +(Optional)

StartTime is the time the build is actually started.

-completionTime,omitEmpty
+completionTime
 Kubernetes meta/v1.Time @@ -728,12 +766,13 @@ Kubernetes meta/v1.Time +(Optional)

CompletionTime is the time the build completed.

-stepStates,omitEmpty
+stepStates
 []Kubernetes core/v1.ContainerState @@ -741,6 +780,7 @@ Kubernetes meta/v1.Time +(Optional)

StepStates describes the state of each build step container.

@@ -752,6 +792,7 @@ Kubernetes meta/v1.Time +(Optional)

StepsCompleted lists the name of build steps completed.

@@ -765,6 +806,7 @@ github.com/knative/pkg/apis/duck/v1alpha1.Conditions +(Optional)

Conditions describes the set of conditions of this build.

@@ -802,10 +844,9 @@ int64 (Optional) -

TODO: Generation does not work correctly with CRD. They are scrubbed -by the APIserver (https://github.com/kubernetes/kubernetes/issues/58778) -So, we add Generation here. Once that gets fixed, remove this and use -ObjectMeta.Generation instead.

+

TODO(dprotaso) Metadata.Generation should increment so we +can drop this property when conversion webhooks enable us +to migrate

@@ -1099,6 +1140,7 @@ GitSourceSpec +(Optional)

Git represents source in a Git repository.

@@ -1112,6 +1154,7 @@ GCSSourceSpec +(Optional)

GCS represents source in Google Cloud Storage.

@@ -1125,6 +1168,7 @@ Kubernetes core/v1.Container +(Optional)

Custom indicates that source should be retrieved using a custom process defined in a container invocation.

@@ -1137,12 +1181,43 @@ string +(Optional)

SubPath specifies a path within the fetched source which should be built. This option makes parent directories inaccessible to the build steps. (The specific source type may, in fact, not even fetch files not in the SubPath.)

+ + +name
+ +string + + + +(Optional) +

Name is the name of source. This field is used to uniquely identify the +source init containers +Restrictions on the allowed charatcers +Must be a basename (no /) +Must be a valid DNS name (only alphanumeric characters, no _) +https://tools.ietf.org/html/rfc1123#section-2

+ + + + +targetPath
+ +string + + + +

TargetPath is the path in workspace directory where the source will be copied. +TargetPath is optional and if its not set source will be copied under workspace. +TargetPath should not be set for custom source.

+ +

Template @@ -1177,8 +1252,8 @@ string -

Name references the BuildTemplate resource to use.

-

The template is assumed to exist in the Build’s namespace.

+

Name references the BuildTemplate resource to use. +The template is assumed to exist in the Build’s namespace.

@@ -1191,6 +1266,7 @@ TemplateKind +(Optional)

The Kind of the template to be used, possible values are BuildTemplate or ClusterBuildTemplate. If nothing is specified, the default if is BuildTemplate

@@ -1205,6 +1281,7 @@ or ClusterBuildTemplate. If nothing is specified, the default if is BuildTemplat +(Optional)

Arguments, if specified, lists values that should be applied to the parameters specified by the template.

@@ -1219,6 +1296,7 @@ parameters specified by the template.

+(Optional)

Env, if specified will provide variables to all build template steps. This will override any of the template’s steps environment variables.

@@ -1237,5 +1315,5 @@ This will override any of the template’s steps environment variables.

Generated with gen-crd-api-reference-docs -on git commit 9485975. +on git commit 695fd25.

diff --git a/docs/reference/eventing/_index.md b/docs/reference/eventing/_index.md new file mode 100644 index 000000000..d16732c1c --- /dev/null +++ b/docs/reference/eventing/_index.md @@ -0,0 +1,8 @@ +--- +title: "Knative Eventing Component" +linkTitle: "Eventing API" +weight: 30 +type: "docs" +--- + +{{% readfile file="eventing.md" relative="true" %}} diff --git a/docs/reference/eventing/eventing-sources-api.md b/docs/reference/eventing/eventing-sources-api.md new file mode 100644 index 000000000..56a3c94c3 --- /dev/null +++ b/docs/reference/eventing/eventing-sources-api.md @@ -0,0 +1,8 @@ +--- +title: "Knative Eventing Sources" +linkTitle: "Eventing-sources API" +weight: 50 +type: "docs" +--- + +{{% readfile file="eventing-sources.md" relative="true" %}} diff --git a/docs/reference/eventing/eventing-sources.md b/docs/reference/eventing/eventing-sources.md index ef3f2cb76..0b20a45dc 100644 --- a/docs/reference/eventing/eventing-sources.md +++ b/docs/reference/eventing/eventing-sources.md @@ -10,14 +10,141 @@

Resource Types: +

AwsSqsSource +

+

+

AwsSqsSource is the Schema for the AWS SQS API

+

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+apiVersion
+string		 + +sources.eventing.knative.dev/v1alpha1 + +
+kind
+string +		AwsSqsSource
+metadata
+ + +Kubernetes meta/v1.ObjectMeta + + +		 +Refer to the Kubernetes API documentation for the fields of the +metadata field. +
+spec
+ + +AwsSqsSourceSpec + + +		 +
+
+ + + + + + + + + + + + + + + + + +
+queueUrl
+ +string + +		 +

QueueURL of the SQS queue that we will poll from.

+
+awsCredsSecret
+ + +Kubernetes core/v1.SecretKeySelector + + +		 +

AwsCredsSecret is the credential to use to poll the AWS SQS

+
+sink
+ + +Kubernetes core/v1.ObjectReference + + +		 +(Optional) +

Sink is a reference to an object that will resolve to a domain name to +use as the sink. This is where events will be received.

+
+serviceAccountName
+ +string + +		 +

ServiceAccoutName is the name of the ServiceAccount that will be used to +run the Receive Adapter Deployment.

+
+
+status
+ + +AwsSqsSourceStatus + + +		 +

ContainerSource

@@ -156,10 +283,10 @@ ContainerSourceStatus -

GcpPubSubSource +

CronJobSource

-

GcpPubSubSource is the Schema for the gcppubsubsources API.

+

CronJobSource is the Schema for the cronjobsources API.

@@ -184,7 +311,7 @@ sources.eventing.knative.dev/v1alpha1 kind
string - + @@ -215,42 +342,24 @@ GcpPubSubSourceSpec
GcpPubSubSourceCronJobSource
@@ -204,8 +331,8 @@ Refer to the Kubernetes API documentation for the fields of the spec
- -GcpPubSubSourceSpec + +CronJobSourceSpec
- - - - @@ -286,8 +395,8 @@ Adapter Deployment.

@@ -571,6 +680,121 @@ KubernetesEventSourceStatus
-gcpCredsSecret
- - -Kubernetes core/v1.SecretKeySelector - - -		 -

GcpCredsSecret is the credential to use to poll the GCP PubSub Subscription. It is not used -to create or delete the Subscription, only to poll it. The value of the secret entry must be -a service account key in the JSON format (see -https://cloud.google.com/iam/docs/creating-managing-service-account-keys).

-
-googleCloudProject
+schedule
string 		-

GoogleCloudProject is the ID of the Google Cloud Project that the PubSub Topic exists in.

+

Schedule is the cronjob schedule.
-topic
+data
string 		-

Topic is the ID of the GCP PubSub Topic to Subscribe to. It must be in the form of the -unique identifier within the project, not the entire name. E.g. it must be ‘laconia’, not -‘projects/my-gcp-project/topics/laconia’.

+

Data is the data posted to the target function.
status
- -GcpPubSubSourceStatus + +CronJobSourceStatus
+

AwsSqsSourceSpec +

+

+(Appears on: +AwsSqsSource) +

+

+

AwsSqsSourceSpec defines the desired state of the source.

+

+ + + + + + + + + + + + + + + + + + + + + + + + + +
FieldDescription
+queueUrl
+ +string + +		 +

QueueURL of the SQS queue that we will poll from.

+
+awsCredsSecret
+ + +Kubernetes core/v1.SecretKeySelector + + +		 +

AwsCredsSecret is the credential to use to poll the AWS SQS

+
+sink
+ + +Kubernetes core/v1.ObjectReference + + +		 +(Optional) +

Sink is a reference to an object that will resolve to a domain name to +use as the sink. This is where events will be received.

+
+serviceAccountName
+ +string + +		 +

ServiceAccoutName is the name of the ServiceAccount that will be used to +run the Receive Adapter Deployment.

+
+

AwsSqsSourceStatus +

+

+(Appears on: +AwsSqsSource) +

+

+

AwsSqsSourceStatus defines the observed state of the source.

+

+ + + + + + + + + + + + + + + + + +
FieldDescription
+conditions
+ + +github.com/knative/pkg/apis/duck/v1alpha1.Conditions + + +		 +(Optional) +

Conditions holds the state of a source at a point in time.

+
+sinkUri
+ +string + +		 +(Optional) +

SinkURI is the current active sink URI that has been configured for the source.

+

ContainerSourceSpec

@@ -699,14 +923,14 @@ string -

GcpPubSubSourceSpec +

CronJobSourceSpec

(Appears on: -GcpPubSubSource) +CronJobSource)

-

GcpPubSubSourceSpec defines the desired state of the GcpPubSubSource.

+

CronJobSourceSpec defines the desired state of the CronJobSource.

@@ -718,42 +942,24 @@ string - - - - @@ -784,14 +990,14 @@ Adapter Deployment.

-gcpCredsSecret
- - -Kubernetes core/v1.SecretKeySelector - - -		 -

GcpCredsSecret is the credential to use to poll the GCP PubSub Subscription. It is not used -to create or delete the Subscription, only to poll it. The value of the secret entry must be -a service account key in the JSON format (see -https://cloud.google.com/iam/docs/creating-managing-service-account-keys).

-
-googleCloudProject
+schedule
string 		-

GoogleCloudProject is the ID of the Google Cloud Project that the PubSub Topic exists in.

+

Schedule is the cronjob schedule.
-topic
+data
string 		-

Topic is the ID of the GCP PubSub Topic to Subscribe to. It must be in the form of the -unique identifier within the project, not the entire name. E.g. it must be ‘laconia’, not -‘projects/my-gcp-project/topics/laconia’.

+

Data is the data posted to the target function.
-

GcpPubSubSourceStatus +

CronJobSourceStatus

(Appears on: -GcpPubSubSource) +CronJobSource)

-

GcpPubSubSourceStatus defines the observed state of GcpPubSubSource.

+

CronJobSourceStatus defines the observed state of CronJobSource.

@@ -824,7 +1030,7 @@ string @@ -1131,5 +1337,5 @@ Kubernetes core/v1.SecretKeySelector

Generated with gen-crd-api-reference-docs -on git commit 9741f15. +on git commit 9236f7c.

diff --git a/docs/reference/eventing/eventing.md b/docs/reference/eventing/eventing.md index 127a02477..ecf839209 100644 --- a/docs/reference/eventing/eventing.md +++ b/docs/reference/eventing/eventing.md @@ -281,10 +281,10 @@ int64 @@ -415,10 +415,10 @@ int64
(Optional) -

SinkURI is the current active sink URI that has been configured for the GcpPubSubSource.

+

SinkURI is the current active sink URI that has been configured for the CronJobSource.
(Optional) -

TODO: Generation does not work correctly with CRD. They are scrubbed -by the APIserver (https://github.com/kubernetes/kubernetes/issues/58778) -So, we add Generation here. Once that gets fixed, remove this and use -ObjectMeta.Generation instead.

+

TODO By enabling the status subresource metadata.generation should increment +thus making this property obsolete.

+

We should be able to drop this property with a CRD conversion webhook +in the future
(Optional) -

TODO: Generation does not work correctly with CRD. They are scrubbed -by the APIserver (https://github.com/kubernetes/kubernetes/issues/58778) -So, we add Generation here. Once that gets fixed, remove this and use -ObjectMeta.Generation instead.

+

TODO By enabling the status subresource metadata.generation should increment +thus making this property obsolete.

+

We should be able to drop this property with a CRD conversion webhook +in the future
@@ -507,10 +507,10 @@ int64 (Optional) -

TODO: Generation used to not work correctly with CRD. They were scrubbed -by the APIserver (https://github.com/kubernetes/kubernetes/issues/58778) -So, we add Generation here. Once the above bug gets rolled out to production -clusters, remove this and use ObjectMeta.Generation instead.

+

TODO By enabling the status subresource metadata.generation should increment +thus making this property obsolete.

+

We should be able to drop this property with a CRD conversion webhook +in the future

@@ -622,10 +622,10 @@ int64 (Optional) -

TODO: Generation does not work correctly with CRD. They are scrubbed -by the APIserver (https://github.com/kubernetes/kubernetes/issues/58778) -So, we add Generation here. Once that gets fixed, remove this and use -ObjectMeta.Generation instead.

+

TODO By enabling the status subresource metadata.generation should increment +thus making this property obsolete.

+

We should be able to drop this property with a CRD conversion webhook +in the future

@@ -760,10 +760,10 @@ int64 (Optional) -

TODO: Generation does not work correctly with CRD. They are scrubbed -by the APIserver (https://github.com/kubernetes/kubernetes/issues/58778) -So, we add Generation here. Once that gets fixed, remove this and use -ObjectMeta.Generation instead.

+

TODO By enabling the status subresource metadata.generation should increment +thus making this property obsolete.

+

We should be able to drop this property with a CRD conversion webhook +in the future

@@ -966,10 +966,10 @@ int64 (Optional) -

TODO: Generation used to not work correctly with CRD. They were scrubbed -by the APIserver (https://github.com/kubernetes/kubernetes/issues/58778) -So, we add Generation here. Once the above bug gets rolled out to production -clusters, remove this and use ObjectMeta.Generation instead.

+

TODO By enabling the status subresource metadata.generation should increment +thus making this property obsolete.

+

We should be able to drop this property with a CRD conversion webhook +in the future

@@ -1065,7 +1065,7 @@ github.com/knative/pkg/apis/duck/v1alpha1.Conditions -physicalSubscription,omitEmpty
+physicalSubscription
SubscriptionStatusPhysicalSubscription @@ -1098,7 +1098,7 @@ Subscription.

-subscriberURI,omitEmpty
+subscriberURI
string @@ -1109,7 +1109,7 @@ string -replyURI,omitEmpty
+replyURI
string @@ -1123,5 +1123,5 @@ string

Generated with gen-crd-api-reference-docs -on git commit 90852711. +on git commit 4712e3a4.

diff --git a/docs/reference/gen-api-reference-docs.sh b/docs/reference/gen-api-reference-docs.sh deleted file mode 100755 index 818379eff..000000000 --- a/docs/reference/gen-api-reference-docs.sh +++ /dev/null @@ -1,165 +0,0 @@ -#!/usr/bin/env bash -# -# This script is for generating API reference docs for Knative components. - -# Copyright 2018 Knative authors -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. -set -euo pipefail - -SCRIPTDIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )" -[[ -n "${DEBUG:-}" ]] && set -x - -REFDOCS_PKG="github.com/ahmetb/gen-crd-api-reference-docs" -REFDOCS_REPO="https://${REFDOCS_PKG}.git" -REFDOCS_VER="5c208a6" - -KNATIVE_SERVING_REPO="github.com/knative/serving" -KNATIVE_SERVING_COMMIT="v0.2.3" -KNATIVE_SERVING_OUT_FILE="reference/serving.md" - -KNATIVE_BUILD_REPO="github.com/knative/build" -KNATIVE_BUILD_COMMIT="v0.2.0" -KNATIVE_BUILD_OUT_FILE="reference/build.md" - -KNATIVE_EVENTING_REPO="github.com/knative/eventing" -KNATIVE_EVENTING_COMMIT="v0.2.1" -KNATIVE_EVENTING_OUT_FILE="reference/eventing/eventing.md" - -KNATIVE_EVENTING_SOURCES_REPO="github.com/knative/eventing-sources" -KNATIVE_EVENTING_SOURCES_COMMIT="v0.2.1" -KNATIVE_EVENTING_SOURCES_OUT_FILE="reference/eventing/eventing-sources.md" - -log() { - echo "$@" >&2 -} - -fail() { - log "error: $*" - exit 1 -} - -install_go_bin() { - local pkg - pkg="$1" - ( - cd "$(mktemp -d)" - go mod init tmp - go get -u "$pkg" - # will be downloaded to "$(go env GOPATH)/bin/$(basename $pkg)" - ) -} - -repo_tarball_url() { - local repo commit - repo="$1" - commit="$2" - echo "https://$repo/archive/$commit.tar.gz" -} - -dl_and_extract() { - # TODO(ahmetb) remove this function. no longer dl'ing tarballs since they - # won't have a .git dir to infer the commit ID from to be used by refdocs. - local url dest - url="$1" - dest="$2" - mkdir -p "${dest}" - curl -sSLf "$url" | tar zxf - --directory="$dest" --strip 1 -} - -clone_at_commit() { - local repo commit dest - repo="$1" - commit="$2" - dest="$3" - mkdir -p "${dest}" - git clone "${repo}" "${dest}" - git --git-dir="${dest}/.git" --work-tree="${dest}" checkout --detach --quiet "${commit}" -} - -gen_refdocs() { - local refdocs_bin gopath out_file repo_root - refdocs_bin="$1" - gopath="$2" - out_file="$3" - repo_root="$4" - - ( - cd "${repo_root}" - env GOPATH="${gopath}" "${refdocs_bin}" \ - -out-file "${gopath}/out/${out_file}" \ - -api-dir "./pkg/apis" \ - -config "${SCRIPTDIR}/knative-refdocs-gen-config.json" - ) -} - - -main() { - if [[ -n "${GOPATH:-}" ]]; then - fail "GOPATH should not be set." - fi - if ! command -v "go" 1>/dev/null ; then - fail "\"go\" is not in PATH" - fi - - # install and place the refdocs tool - local refdocs_bin refdocs_bin_expected refdocs_dir - refdocs_dir="$(mktemp -d)" - refdocs_bin="${refdocs_dir}/refdocs" - # clone repo for ./templates - git clone --quiet --depth=1 "${REFDOCS_REPO}" "${refdocs_dir}" - # install bin - install_go_bin "${REFDOCS_PKG}@${REFDOCS_VER}" - # move bin to final location - refdocs_bin_expected="$(go env GOPATH)/bin/$(basename ${REFDOCS_PKG})" - mv "${refdocs_bin_expected}" "${refdocs_bin}" - [[ ! -f "${refdocs_bin}" ]] && fail "refdocs failed to install" - - local clone_root - clone_root="$(mktemp -d)" - - local knative_serving_root - knative_serving_root="${clone_root}/src/${KNATIVE_SERVING_REPO}" - clone_at_commit "https://${KNATIVE_SERVING_REPO}.git" "${KNATIVE_SERVING_COMMIT}" \ - "${knative_serving_root}" - gen_refdocs "${refdocs_bin}" "${clone_root}" "${KNATIVE_SERVING_OUT_FILE}" \ - "${knative_serving_root}" - - local knative_build_root - knative_build_root="${clone_root}/src/${KNATIVE_BUILD_REPO}" - clone_at_commit "https://${KNATIVE_BUILD_REPO}.git" "${KNATIVE_BUILD_COMMIT}" \ - "${knative_build_root}" - gen_refdocs "${refdocs_bin}" "${clone_root}" "${KNATIVE_BUILD_OUT_FILE}" \ - "${knative_build_root}" - - local knative_eventing_root - knative_eventing_root="${clone_root}/src/${KNATIVE_EVENTING_REPO}" - clone_at_commit "https://${KNATIVE_EVENTING_REPO}.git" "${KNATIVE_EVENTING_COMMIT}" \ - "${knative_eventing_root}" - gen_refdocs "${refdocs_bin}" "${clone_root}" "${KNATIVE_EVENTING_OUT_FILE}" \ - "${knative_eventing_root}" - - local knative_eventing_sources_root - knative_eventing_sources_root="${clone_root}/src/${KNATIVE_EVENTING_SOURCES_REPO}" - clone_at_commit "https://${KNATIVE_EVENTING_SOURCES_REPO}.git" "${KNATIVE_EVENTING_SOURCES_COMMIT}" \ - "${knative_eventing_sources_root}" - gen_refdocs "${refdocs_bin}" "${clone_root}" "${KNATIVE_EVENTING_SOURCES_OUT_FILE}" \ - "${knative_eventing_sources_root}" - - log "Generated files written to ${clone_root}/out/." - if command -v open >/dev/null; then - open "${clone_root}/out/" - fi -} - -main "$@" diff --git a/docs/reference/knative-refdocs-gen-config.json b/docs/reference/knative-refdocs-gen-config.json deleted file mode 100644 index e5fdbc706..000000000 --- a/docs/reference/knative-refdocs-gen-config.json +++ /dev/null @@ -1,28 +0,0 @@ -{ - "hideMemberFields": [ - "TypeMeta" - ], - "hideTypePatterns": [ - "ParseError$", - "List$" - ], - "externalPackages": [ - { - "typeMatchPrefix": "^k8s\\.io/apimachinery/pkg/apis/meta/v1\\.Duration$", - "docsURLTemplate": "https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#Duration" - }, - { - "typeMatchPrefix": "^k8s\\.io/(api|apimachinery/pkg/apis)/", - "docsURLTemplate": "https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.13/#{{lower .TypeIdentifier}}-{{arrIndex .PackageSegments -1}}-{{arrIndex .PackageSegments -2}}" - }, - { - "typeMatchPrefix": "^github\\.com/knative/pkg/apis/duck/", - "docsURLTemplate": "https://godoc.org/github.com/knative/pkg/apis/duck/{{arrIndex .PackageSegments -1}}#{{.TypeIdentifier}}" - } - ], - "typeDisplayNamePrefixOverrides": { - "k8s.io/api/": "Kubernetes ", - "k8s.io/apimachinery/pkg/apis/": "Kubernetes " - }, - "markdownDisabled": false -} diff --git a/docs/reference/serving-api.md b/docs/reference/serving-api.md new file mode 100644 index 000000000..3e370cfa7 --- /dev/null +++ b/docs/reference/serving-api.md @@ -0,0 +1,8 @@ +--- +title: "Knative Serving Component" +linkTitle: "Serving API" +weight: 50 +type: "docs" +--- + +{{% readfile file="serving.md" relative="true" %}} diff --git a/docs/reference/serving.md b/docs/reference/serving.md index 6202c01d0..513cfcc32 100644 --- a/docs/reference/serving.md +++ b/docs/reference/serving.md @@ -425,6 +425,19 @@ ingress supports SNI.

A list of host rules used to configure the ClusterIngress.

+ + +visibility
+ + +IngressVisibility + + + + +

Visibility setting.

+ + @@ -931,6 +944,19 @@ ingress supports SNI.

A list of host rules used to configure the ClusterIngress.

+ + +visibility
+ + +IngressVisibility + + + + +

Visibility setting.

+ +

IngressStatus @@ -979,6 +1005,16 @@ LoadBalancerStatus +

IngressVisibility +(string alias)

+

+(Appears on: +IngressSpec) +

+

+

IngressVisibility describes whether the Ingress should be exposed to +public gateways or not.

+

LoadBalancerIngressStatus

@@ -1037,6 +1073,18 @@ string DNS name to allow routing in case of not having a mesh.

+ + +meshOnly
+ +bool + + + +(Optional) +

MeshOnly is set if the ClusterIngress is only load-balanced through a Service mesh.

+ +

LoadBalancerStatus @@ -1414,6 +1462,18 @@ TODO(mattmoor): Link to the runtime contract tracked by: https://github.com/knative/serving/issues/627

+ + +timeoutSeconds
+ +int64 + + + +(Optional) +

TimeoutSeconds holds the max duration the instance is allowed for responding to a request.

+ + @@ -2209,6 +2269,18 @@ TODO(mattmoor): Link to the runtime contract tracked by: https://github.com/knative/serving/issues/627

+ + +timeoutSeconds
+ +int64 + + + +(Optional) +

TimeoutSeconds holds the max duration the instance is allowed for responding to a request.

+ +

RevisionStatus @@ -2483,6 +2555,18 @@ TODO(mattmoor): Link to the runtime contract tracked by: https://github.com/knative/serving/issues/627

+ + +timeoutSeconds
+ +int64 + + + +(Optional) +

TimeoutSeconds holds the max duration the instance is allowed for responding to a request.

+ + @@ -2991,5 +3075,5 @@ This defaults to zero if unspecified.

Generated with gen-crd-api-reference-docs -on git commit 5cbee406. +on git commit 4d198db8.

diff --git a/docs/serving/README.md b/docs/serving/README.md index 7f5796e98..9f5fcbf08 100644 --- a/docs/serving/README.md +++ b/docs/serving/README.md @@ -1,4 +1,3 @@ -# Knative Serving Knative Serving builds on Kubernetes and Istio to support deploying and serving of serverless applications and functions. Serving is easy to get started with @@ -41,7 +40,7 @@ serverless workload behaves on the cluster: ## Getting Started -To get started with Serving, check out one of the [hello world](samples/) sample +To get started with Serving, check out one of the [hello world](./samples/) sample projects. These projects use the `Service` resource, which manages all of the details for you. diff --git a/docs/serving/_index.md b/docs/serving/_index.md new file mode 100644 index 000000000..b63deb17e --- /dev/null +++ b/docs/serving/_index.md @@ -0,0 +1,8 @@ +--- +title: "Knative Serving" +linkTitle: "Serving Component" +weight: 20 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/serving/accessing-logs.md b/docs/serving/accessing-logs.md index 5bee22f0c..8bd2354fe 100644 --- a/docs/serving/accessing-logs.md +++ b/docs/serving/accessing-logs.md @@ -1,4 +1,8 @@ -# Accessing logs +--- +title: "Accessing logs" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 5 +--- If you have not yet installed the logging and monitoring components, go through the [installation instructions](./installing-logging-metrics-traces.md) to set @@ -23,7 +27,7 @@ up the necessary components first. The Discover tab of the Kibana UI looks like this: - ![Kibana UI Discover tab](./images/kibana-discover-tab-annotated.png) + ![Kibana UI Discover tab](../images/kibana-discover-tab-annotated.png) You can change the time frame of logs Kibana displays in the upper right corner of the screen. The main search bar is across the top of the Discover diff --git a/docs/serving/accessing-metrics.md b/docs/serving/accessing-metrics.md index 722a9e2d1..500e62d59 100644 --- a/docs/serving/accessing-metrics.md +++ b/docs/serving/accessing-metrics.md @@ -1,4 +1,8 @@ -# Accessing metrics +--- +title: "Accessing metrics" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 10 +--- You access metrics through the [Grafana](https://grafana.com/) UI. Grafana is the visualization tool for [Prometheus](https://prometheus.io/). @@ -21,7 +25,7 @@ $(kubectl get pods --namespace knative-monitoring \ 3. Select the **Home** button on the top of the page to see the list of pre-installed dashboards (screenshot below): - ![Knative Dashboards](./images/grafana1.png) + ![Knative Dashboards](../images/grafana1.png) The following dashboards are pre-installed with Knative Serving: diff --git a/docs/serving/accessing-traces.md b/docs/serving/accessing-traces.md index ae21bb1e1..fb6762386 100644 --- a/docs/serving/accessing-traces.md +++ b/docs/serving/accessing-traces.md @@ -1,4 +1,8 @@ -# Accessing request traces +--- +title: "Accessing request traces" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 15 +--- If you have not yet installed the logging and monitoring components, go through the [installation instructions](./installing-logging-metrics-traces.md) to set diff --git a/docs/serving/cluster-local-route.md b/docs/serving/cluster-local-route.md index 6c7c38983..845acc84e 100644 --- a/docs/serving/cluster-local-route.md +++ b/docs/serving/cluster-local-route.md @@ -1,4 +1,8 @@ -# Making your Routes local to the cluster +--- +title: "Making your Routes local to the cluster" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 20 +--- In Knative 0.3.x or later, all Routes with a domain suffix of `svc.cluster.local` will only be visible inside the cluster. diff --git a/docs/serving/debugging-application-issues.md b/docs/serving/debugging-application-issues.md index 0562672f7..8fb4682da 100644 --- a/docs/serving/debugging-application-issues.md +++ b/docs/serving/debugging-application-issues.md @@ -1,4 +1,8 @@ -# Debugging Issues with Your Application +--- +title: "Debugging issues with your application" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 25 +--- You deployed your app to Knative Serving, but it isn't working as expected. Go through this step-by-step guide to understand what failed. @@ -189,9 +193,8 @@ kubectl get build $(kubectl get revision --output jsonpath="{.sp If there is any failure, the `conditions` in `status` provide the reason. To access build logs, first execute `kubectl proxy` and then open [Kibana UI](http://localhost:8001/api/v1/namespaces/knative-monitoring/services/kibana-logging/proxy/app/kibana). -Use any of the following filters within Kibana UI to see build logs. _(See -[telemetry guide](../telemetry.md) for more information on logging and -monitoring features of Knative Serving.)_ +Use any of the following filters within Kibana UI to see build logs. For more information about the Knative +observability features, see [Installing logging, metrics, and traces](./Installing-logging-metrics-traces.md). - All build logs: `_exists_:"kubernetes.labels.build-name"` - Build logs for a specific build: `kubernetes.labels.build-name:""` diff --git a/docs/serving/debugging-performance-issues.md b/docs/serving/debugging-performance-issues.md index b4b4af0ea..f31f95f37 100644 --- a/docs/serving/debugging-performance-issues.md +++ b/docs/serving/debugging-performance-issues.md @@ -1,4 +1,8 @@ -# Investigating Performance Issues +--- +title: "Investigating performance issues" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 30 +--- You deployed your application or function to Knative Serving but its performance doesn't meet your expectations. Knative Serving provides various dashboards and @@ -16,7 +20,7 @@ Start your investigation with the "Revision - HTTP Requests" dashboard. 1. Select your configuration and revision from the menu on top left of the page. You will see a page like this: - ![Knative Serving - Revision HTTP Requests](./images/request_dash1.png) + ![Knative Serving - Revision HTTP Requests](../images/request_dash1.png) This dashboard gives visibility into the following for each revision: @@ -42,7 +46,7 @@ request. 1. Select your revision from the "Service Name" dropdown, and then click the "Find Traces" button. You'll get a view that looks like this: - ![Zipkin - Trace Overview](./images/zipkin1.png) + ![Zipkin - Trace Overview](../images/zipkin1.png) In this example, you can see that the request spent most of its time in the [span](https://github.com/opentracing/specification/blob/master/specification.md#the-opentracing-data-model) @@ -50,7 +54,7 @@ request. 1. Click that span to see a view like the following: - ![Zipkin - Span Details](./images/zipkin2.png) + ![Zipkin - Span Details](../images/zipkin2.png) This view shows detailed information about the specific span, such as the micro service or external URL that was called. In this example, the call to @@ -66,7 +70,7 @@ next. 1. To open the autoscaler dashboard, open Grafana UI and select "Knative Serving - Autoscaler" dashboard, which looks like this: - ![Knative Serving - Autoscaler](./images/autoscaler_dash1.png) + ![Knative Serving - Autoscaler](../images/autoscaler_dash1.png) This view shows 4 key metrics from the Knative Serving autoscaler: @@ -94,7 +98,7 @@ the traffic but was only granted 8 pods because the cluster is out of resources. You can access total CPU and memory usage of your revision from the "Knative Serving - Revision CPU and Memory Usage" dashboard, which looks like this: -![Knative Serving - Revision CPU and Memory Usage](./images/cpu_dash1.png) +![Knative Serving - Revision CPU and Memory Usage](../images/cpu_dash1.png) The first chart shows rate of the CPU usage across all pods serving the revision. The second chart shows total memory consumed across all pods serving diff --git a/docs/serving/deploying-with-private-registry.md b/docs/serving/deploying-with-private-registry.md index c82a506e7..686048288 100644 --- a/docs/serving/deploying-with-private-registry.md +++ b/docs/serving/deploying-with-private-registry.md @@ -1,11 +1,19 @@ -# Deploying to Knative using a private container registry -This guide walks you through deploying an application to Knative from source code in a git repository using a private container registry for the container image. The source code should contain a dockerfile. For this guide, we'll use this [helloworld app](https://github.com/knative/docs/tree/master/serving/samples/helloworld-go), but you could use your own. +--- +title: "Deploying to Knative using a private container registry" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 10 +--- +This guide walks you through deploying an application to Knative from source +code in a git repository using a private container registry for the container +image. The source code should contain a dockerfile. For this guide, we'll use +this [helloworld app](./samples/hello-world/helloworld-go), but you could use +your own. ## Set up a private container registry and obtain credentials If you do not want your container image to be publicly available, you may want to use a private container registry. In this example, we'll use IBM Container Registry, but most of these concepts will be similar for other clouds. -1. Ensure you have the [IBM Cloud CLI](https://cloud.ibm.com/docs/cli/reference/ibmcloud/download_cli.html#install_use) installed. +1. Ensure you have the [IBM Cloud CLI](https://cloud.ibm.com/docs/cli/reference/ibmcloud/download_cli.html#install_use) installed. 1. Install the container registry plugin: @@ -13,12 +21,12 @@ If you do not want your container image to be publicly available, you may want t ibmcloud plugin install container-registry ``` -1. Choose a name for your first namespace, and then create it: +1. Choose a name for your first namespace, and then create it: ``` ibmcloud cr namespace-add ``` - + A namespace represents the spot within a registry that holds your images. You can set up multiple namespaces as well as control access to your namespaces by using IAM policies. 1. Create a token: @@ -26,7 +34,7 @@ If you do not want your container image to be publicly available, you may want t ``` ibmcloud cr token-add --description "token description" --non-expiring --readwrite ``` - + The automated build processes you'll be setting up will use this token to access your images. 1. The CLI output should include a token identifier and the token. Make note of the token. You can verify that the token was created by listing all tokens: @@ -59,13 +67,13 @@ A Secret is a Kubernetes object containing sensitive data such as a password, a 1. Apply the secret to your cluster. - ``` + ```bash kubectl apply --filename registry-push-secret.yaml ``` 1. You will also need a secret for the knative-serving component to pull down an image from the private container registry. This secret will be a `docker-registry` type secret. You can create this via the commandline. For username, simply use the string `token`. For , use the token you made note of earlier. - ``` + ```bash kubectl create secret docker-registry ibm-cr-secret --docker-server=https://registry.ng.bluemix.net --docker-username=token --docker-password= ``` @@ -86,7 +94,7 @@ A Service Account provides an identity for processes that run in a Pod. This Ser 1. Apply the service account to your cluster: - ``` + ```bash kubectl apply --filename service-account.yaml ``` @@ -95,7 +103,7 @@ To build our application from the source on GitHub, and push the resulting image 1. Install the Kaniko build template - ``` + ```bash kubectl apply --filename https://raw.githubusercontent.com/knative/build-templates/master/kaniko/kaniko.yaml ``` @@ -119,7 +127,7 @@ To build our application from the source on GitHub, and push the resulting image git: url: https://github.com/knative/docs revision: master - subPath: serving/samples/helloworld-go + subPath: docs/serving/samples/hello-world/helloworld-go template: name: kaniko arguments: @@ -129,7 +137,7 @@ To build our application from the source on GitHub, and push the resulting image spec: serviceAccountName: build-bot container: - image: registry.ng.bluemix.net/{NAMESPACE}/helloworld-go:latest + image: registry.ng.bluemix.net/{NAMESPACE}/helloworld-go:latest imagePullPolicy: Always env: - name: TARGET @@ -137,8 +145,8 @@ To build our application from the source on GitHub, and push the resulting image ``` 1. Apply the configuration using `kubectl`: - - ``` + + ```bash kubectl apply --filename service.yaml ``` diff --git a/docs/serving/fluentd/README.md b/docs/serving/fluentd-requirements.md similarity index 89% rename from docs/serving/fluentd/README.md rename to docs/serving/fluentd-requirements.md index e6b835eda..e5c784e57 100644 --- a/docs/serving/fluentd/README.md +++ b/docs/serving/fluentd-requirements.md @@ -1,4 +1,9 @@ -# Fluentd Docker Image on Knative Serving +--- +title: "Fluentd container image requirements" +linkTitle: "Fluentd requirements" +weight: 10 +type: "docs" +--- Knative Serving uses a [Fluentd](https://www.fluentd.org/) docker image to collect logs. Operators can customize their own Fluentd docker image and @@ -32,7 +37,7 @@ that allows sending logs to a Elasticsearch service. ### Send logs to Stackdriver -This sample [Dockerfile](stackdriver/Dockerfile) is based on +This sample [Dockerfile](./stackdriver/Dockerfile) is based on [k8s.gcr.io/fluentd-elasticsearch:v2.0.4](https://github.com/kubernetes/kubernetes/tree/master/cluster/addons/fluentd-elasticsearch). It additionally adds one more plugin - [fluent-plugin-google-cloud](https://github.com/GoogleCloudPlatform/fluent-plugin-google-cloud) @@ -40,7 +45,7 @@ which allows sending logs to Stackdriver. Operators can build this image and push it to a container registry which their Kubernetes cluster has access to. See -[Setting Up A Logging Plugin](/serving/setting-up-a-logging-plugin.md) for +[Setting Up A Logging Plugin](../setting-up-a-logging-plugin.md) for details. **NOTE**: Operators need to add credentials file the stackdriver agent needs to the docker image if their Knative Serving is not built on a GCP based cluster or they want to send logs to another GCP project. See diff --git a/docs/serving/fluentd/fluentd-requirements.md b/docs/serving/fluentd/fluentd-requirements.md new file mode 100644 index 000000000..e5c784e57 --- /dev/null +++ b/docs/serving/fluentd/fluentd-requirements.md @@ -0,0 +1,53 @@ +--- +title: "Fluentd container image requirements" +linkTitle: "Fluentd requirements" +weight: 10 +type: "docs" +--- + +Knative Serving uses a [Fluentd](https://www.fluentd.org/) docker image to +collect logs. Operators can customize their own Fluentd docker image and +configuration to define logging output. + +## Requirements + +Knative requires the customized Fluentd docker image with the following plugins +installed: + +- [fluentd](https://github.com/fluent/fluentd) >= v0.14.0 +- [fluent-plugin-kubernetes_metadata_filter](https://github.com/fabric8io/fluent-plugin-kubernetes_metadata_filter) >= + 1.0.0 AND < 2.1.0: To enrich log entries with Kubernetes metadata. +- [fluent-plugin-detect-exceptions](https://github.com/GoogleCloudPlatform/fluent-plugin-detect-exceptions) >= + 0.0.9: To combine multi-line exception stack traces logs into one log entry. +- [fluent-plugin-multi-format-parser](https://github.com/repeatedly/fluent-plugin-multi-format-parser) >= + 1.0.0: To detect log format as Json or plain text. + +## Sample images + +Operators can use any Docker image which meets the requirements above and +includes the desired output plugin. Two examples below: + +### Send logs to Elasticsearch + +Operators can use +[k8s.gcr.io/fluentd-elasticsearch:v2.0.4](https://github.com/kubernetes/kubernetes/tree/master/cluster/addons/fluentd-elasticsearch/fluentd-es-image) +which includes +[fluent-plugin-elasticsearch](https://github.com/uken/fluent-plugin-elasticsearch) +that allows sending logs to a Elasticsearch service. + +### Send logs to Stackdriver + +This sample [Dockerfile](./stackdriver/Dockerfile) is based on +[k8s.gcr.io/fluentd-elasticsearch:v2.0.4](https://github.com/kubernetes/kubernetes/tree/master/cluster/addons/fluentd-elasticsearch). +It additionally adds one more plugin - +[fluent-plugin-google-cloud](https://github.com/GoogleCloudPlatform/fluent-plugin-google-cloud) +which allows sending logs to Stackdriver. + +Operators can build this image and push it to a container registry which their +Kubernetes cluster has access to. See +[Setting Up A Logging Plugin](../setting-up-a-logging-plugin.md) for +details. **NOTE**: Operators need to add credentials file the stackdriver agent +needs to the docker image if their Knative Serving is not built on a GCP based +cluster or they want to send logs to another GCP project. See +[here](https://cloud.google.com/logging/docs/agent/authorization) for more +information. diff --git a/docs/serving/gke-assigning-static-ip-address.md b/docs/serving/gke-assigning-static-ip-address.md index 31cea3955..55175efb5 100644 --- a/docs/serving/gke-assigning-static-ip-address.md +++ b/docs/serving/gke-assigning-static-ip-address.md @@ -1,4 +1,8 @@ -# Assigning a static IP address for Knative on Kubernetes Engine +--- +title: "Assigning a static IP address for Knative on Kubernetes Engine" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 35 +--- If you are running Knative on Google Kubernetes Engine and want to use a [custom domain](./using-a-custom-domain.md) with your apps, you need to @@ -13,7 +17,7 @@ Therefore, in order to set a static IP for the gateway you must to set the external IP address of the `istio-ingressgateway` service to a static IP. If you have configured a -[custom ingress gateway](setting-up-custom-ingress-gateway.md), replace +[custom ingress gateway](./setting-up-custom-ingress-gateway.md), replace `istio-ingressgateway` with the name of your gateway service in the steps below. ## Step 1: Reserve a static IP address diff --git a/docs/serving/installing-logging-metrics-traces.md b/docs/serving/installing-logging-metrics-traces.md index 58365b893..23491a23e 100644 --- a/docs/serving/installing-logging-metrics-traces.md +++ b/docs/serving/installing-logging-metrics-traces.md @@ -1,4 +1,8 @@ -# Installing Logging, Metrics, and Traces +--- +title: "Installing logging, metrics, and traces" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 40 +--- If you followed one of the [comprehensive install guides](../install/README.md#install-guides) or you @@ -52,7 +56,7 @@ install: 1. [Elasticsearch and Kibana](#elasticsearch-and-kibana) 1. [Stackdriver](#stackdriver) -1. [Custom logging plugin](setting-up-a-logging-plugin.md) +1. [Custom logging plugin](./setting-up-a-logging-plugin.md) ### Elasticsearch and Kibana @@ -135,7 +139,7 @@ explore. `Index pattern` and select `@timestamp` from `Time Filter field name` and click on `Create` button. -![Create logstash-* index](images/kibana-landing-page-configure-index.png) +![Create logstash-* index](../images/kibana-landing-page-configure-index.png) See [Accessing Logs](./accessing-logs.md) for more information about logs in Knative. @@ -153,9 +157,10 @@ To configure and setup monitoring: ``` 1. Choose a container image that meets the - [Fluentd image requirements](fluentd/README.md#requirements). For example, - you can use a public image. Or you can create a custom one and upload the - image to a container registry which your cluster has read access to. + [Fluentd image requirements](./fluentd-requirements.md#requirements). + For example, you can use a public image. Or you can create a custom one and + upload the image to a container registry which your cluster has read access + to. You must configure and build your own Fluentd image if either of the following are true: @@ -165,7 +170,7 @@ To configure and setup monitoring: - You want to send logs to another GCP project. 1. Follow the instructions in - ["Setting up a logging plugin"](setting-up-a-logging-plugin.md#Configuring) + ["Setting up a logging plugin"](./setting-up-a-logging-plugin.md#Configuring) to configure the stackdriver components settings. 1. Install Knative Stackdriver components by running the following command from diff --git a/docs/serving/outbound-network-access.md b/docs/serving/outbound-network-access.md index 0f08227c4..e940e6469 100644 --- a/docs/serving/outbound-network-access.md +++ b/docs/serving/outbound-network-access.md @@ -1,4 +1,8 @@ -# Configuring outbound network access +--- +title: "Configuring outbound network access" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 45 +--- This guides walks you through enabling outbound network access for a Knative app. diff --git a/docs/serving/samples/README.md b/docs/serving/samples/README.md index d5ee7f830..d124dcf80 100644 --- a/docs/serving/samples/README.md +++ b/docs/serving/samples/README.md @@ -1,23 +1,20 @@ -# Knative serving sample applications - -This directory contains sample applications, developed on Knative, to illustrate -different use-cases and resources. See -[Knative serving](https://github.com/knative/docs/tree/master/serving) to learn -more about Knative Serving resources. +Use the following sample applications to help you understand the various +Knative Serving resources and how they can be applied across common use cases. +[Learn more about Knative Serving resources](../README.md). | Name | Description | Languages | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------: | -| Hello World | A quick introduction that highlights how to deploy an app using Knative Serving. | [C#](helloworld-csharp/README.md), [Go](helloworld-go/README.md), [Java](helloworld-java/README.md), [Kotlin](helloworld-kotlin/README.md), [Node.js](helloworld-nodejs/README.md), [PHP](helloworld-php/README.md), [Python](helloworld-python/README.md), [Ruby](helloworld-ruby/README.md), [Scala](helloworld-scala/README.md) | -| Advanced Deployment | Simple blue/green-like application deployment pattern illustrating the process of updating a live application without dropping any traffic. | [YAML](blue-green-deployment.md) | -| Autoscale | A demonstration of the autoscaling capabilities of Knative. | [Go](autoscale-go/README.md) | -| Private Repo Build | An example of deploying a Knative Serving Service using a Github deploy-key and a DockerHub image pull secret. | [Go](build-private-repo-go/README.md) | -| Buildpack for Applications | A sample app that demonstrates using Cloud Foundry buildpacks on Knative Serving. | [.NET](buildpack-app-dotnet/README.md) | -| Buildpack for Functions | A sample function that demonstrates using Cloud Foundry buildpacks on Knative Serving. | [Node.js](buildpack-function-nodejs/README.md) | -| Github Webhook | A simple webhook handler that demonstrates interacting with Github. | [Go](gitwebhook-go/README.md) | -| gRPC | A simple gRPC server. | [Go](grpc-ping-go/README.md) | -| Knative Routing | An example of mapping multiple Knative services to different paths under a single domain name using the Istio VirtualService concept. | [Go](knative-routing-go/README.md) | -| REST API | A simple Restful service that exposes an endpoint defined by an environment variable described in the Knative Configuration. | [Go](rest-api-go/README.md) | -| Source to URL | A sample that shows how to use Knative to go from source code in a git repository to a running application with a URL. | [Go](source-to-url-go/README.md) | -| Telemetry | This sample runs a simple web server that makes calls to other in-cluster services and responds to requests with "Hello World!". The purpose of this sample is to show generating metrics, logs, and distributed traces. | [Go](telemetry-go/README.md) | -| Thumbnailer | An example of deploying a "dockerized" application to Knative Serving which takes video URL as an input and generates its thumbnail image. | [Go](thumbnailer-go/README.md) | -| Traffic Splitting | This samples builds off the [Creating a RESTful Service](./rest-api-go) sample to illustrate applying a revision, then using that revision for manual traffic splitting. | [YAML](traffic-splitting/README.md) | +| Hello World | A quick introduction that highlights how to deploy an app using Knative Serving. | [C#](./hello-world/helloworld-csharp/README.md), [Go](./hello-world/helloworld-go/README.md), [Java](./hello-world/helloworld-java/README.md), [Kotlin](./hello-world/helloworld-kotlin/README.md), [Node.js](./hello-world/helloworld-nodejs/README.md), [PHP](./hello-world/helloworld-php/README.md), [Python](./hello-world/helloworld-python/README.md), [Ruby](./hello-world/helloworld-ruby/README.md), [Scala](./hello-world/helloworld-scala/README.md) | +| Advanced Deployment | Simple blue/green-like application deployment pattern illustrating the process of updating a live application without dropping any traffic. | [YAML](./blue-green-deployment.md) | +| Autoscale | A demonstration of the autoscaling capabilities of Knative. | [Go](./autoscale-go/README.md) | +| Private Repo Build | An example of deploying a Knative Serving Service using a Github deploy-key and a DockerHub image pull secret. | [Go](./build-private-repo-go/README.md) | +| Buildpack for Applications | A sample app that demonstrates using Cloud Foundry buildpacks on Knative Serving. | [.NET](./buildpack-app-dotnet/README.md) | +| Buildpack for Functions | A sample function that demonstrates using Cloud Foundry buildpacks on Knative Serving. | [Node.js](./buildpack-function-nodejs/README.md) | +| Github Webhook | A simple webhook handler that demonstrates interacting with Github. | [Go](./gitwebhook-go/README.md) | +| gRPC | A simple gRPC server. | [Go](./grpc-ping-go/README.md) | +| Knative Routing | An example of mapping multiple Knative services to different paths under a single domain name using the Istio VirtualService concept. | [Go](./knative-routing-go/README.md) | +| REST API | A simple Restful service that exposes an endpoint defined by an environment variable described in the Knative Configuration. | [Go](./rest-api-go/README.md) | +| Source to URL | A sample that shows how to use Knative to go from source code in a git repository to a running application with a URL. | [Go](./source-to-url-go/README.md) | +| Telemetry | This sample runs a simple web server that makes calls to other in-cluster services and responds to requests with "Hello World!". The purpose of this sample is to show generating metrics, logs, and distributed traces. | [Go](./telemetry-go/README.md) | +| Thumbnailer | An example of deploying a "dockerized" application to Knative Serving which takes video URL as an input and generates its thumbnail image. | [Go](./thumbnailer-go/README.md) | +| Traffic Splitting | This samples builds off the [Creating a RESTful Service](./rest-api-go) sample to illustrate applying a revision, then using that revision for manual traffic splitting. | [YAML](./traffic-splitting/README.md) | diff --git a/docs/serving/samples/_index.md b/docs/serving/samples/_index.md new file mode 100644 index 000000000..312b87b4f --- /dev/null +++ b/docs/serving/samples/_index.md @@ -0,0 +1,8 @@ +--- +title: "Knative Serving Sample Applications" +linkTitle: "Sample Apps" +weight: 1 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/serving/samples/autoscale-go/README.md b/docs/serving/samples/autoscale-go/README.md index ec50949a9..1578382f5 100644 --- a/docs/serving/samples/autoscale-go/README.md +++ b/docs/serving/samples/autoscale-go/README.md @@ -1,122 +1,120 @@ -# Autoscale Sample A demonstration of the autoscaling capabilities of a Knative Serving Revision. ## Prerequisites -1. A Kubernetes cluster with - [Knative Serving](https://github.com/knative/docs/blob/master/install/README.md) +1. A Kubernetes cluster with [Knative Serving](../../../install/README.md) installed. 1. A - [metrics installation](https://github.com/knative/docs/blob/master/serving/installing-logging-metrics-traces.md) + [metrics installation](../../installing-logging-metrics-traces.md) for viewing scaling graphs (optional). 1. The `hey` load generator installed (`go get -u github.com/rakyll/hey`). 1. Clone this repository, and move into the sample directory: - ```shell - git clone https://github.com/knative/docs knative-docs - cd knative-docs - ``` + ```shell + git clone https://github.com/knative/docs knative-docs + cd knative-docs + ``` ## Deploy the Service 1. Deploy the [sample](./service.yaml) Knative Service: - ``` - kubectl apply --filename serving/samples/autoscale-go/service.yaml - ``` + ``` + kubectl apply --filename docs/serving/samples/autoscale-go/service.yaml + ``` 1. Find the ingress hostname and IP and export as an environment variable: - ```shell - # In Knative 0.2.x and prior versions, the `knative-ingressgateway` service was used instead of `istio-ingressgateway`. - INGRESSGATEWAY=knative-ingressgateway + ```shell + # In Knative 0.2.x and prior versions, the `knative-ingressgateway` service was used instead of `istio-ingressgateway`. + INGRESSGATEWAY=knative-ingressgateway - # The use of `knative-ingressgateway` is deprecated in Knative v0.3.x. - # Use `istio-ingressgateway` instead, since `knative-ingressgateway` - # will be removed in Knative v0.4. - if kubectl get configmap config-istio -n knative-serving &> /dev/null; then - INGRESSGATEWAY=istio-ingressgateway - fi + # The use of `knative-ingressgateway` is deprecated in Knative v0.3.x. + # Use `istio-ingressgateway` instead, since `knative-ingressgateway` + # will be removed in Knative v0.4. + if kubectl get configmap config-istio -n knative-serving &> /dev/null; then + INGRESSGATEWAY=istio-ingressgateway + fi - export IP_ADDRESS=`kubectl get svc $INGRESSGATEWAY --namespace istio-system --output jsonpath="{.status.loadBalancer.ingress[*].ip}"` - ``` + export IP_ADDRESS=`kubectl get svc $INGRESSGATEWAY --namespace istio-system --output jsonpath=" . {.status.loadBalancer.ingress[*].ip}"` + ``` ## Load the Service 1. Make a request to the autoscale app to see it consume some resources. - ```shell - curl --header "Host: autoscale-go.default.example.com" "http://${IP_ADDRESS?}?sleep=100&prime=10000&bloat=5" - ``` + ```shell + curl --header "Host: autoscale-go.default.example.com" "http://${IP_ADDRESS?}?sleep=100&prime=10000&bloat=5" + ``` - ``` - Allocated 5 Mb of memory. - The largest prime less than 10000 is 9973. - Slept for 100.13 milliseconds. - ``` + ``` + Allocated 5 Mb of memory. + The largest prime less than 10000 is 9973. + Slept for 100.13 milliseconds. + ``` 1. Send 30 seconds of traffic maintaining 50 in-flight requests. - ```shell - hey -z 30s -c 50 \ - -host "autoscale-go.default.example.com" \ - "http://${IP_ADDRESS?}?sleep=100&prime=10000&bloat=5" \ - && kubectl get pods - ``` + ```shell + hey -z 30s -c 50 \ + -host "autoscale-go.default.example.com" \ + "http://${IP_ADDRESS?}?sleep=100&prime=10000&bloat=5" \ + && kubectl get pods + ``` - ``` - Summary: - Total: 30.3379 secs - Slowest: 0.7433 secs - Fastest: 0.1672 secs - Average: 0.2778 secs - Requests/sec: 178.7861 + ```shell + Summary: + Total: 30.3379 secs + Slowest: 0.7433 secs + Fastest: 0.1672 secs + Average: 0.2778 secs + Requests/sec: 178.7861 - Total data: 542038 bytes - Size/request: 99 bytes + Total data: 542038 bytes + Size/request: 99 bytes - Response time histogram: - 0.167 [1] | - 0.225 [1462] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ - 0.282 [1303] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■ - 0.340 [1894] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ - 0.398 [471] |■■■■■■■■■■ - 0.455 [159] |■■■ - 0.513 [68] |■ - 0.570 [18] | - 0.628 [14] | - 0.686 [21] | - 0.743 [13] | + Response time histogram: + 0.167 [1] | + 0.225 [1462] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 0.282 [1303] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 0.340 [1894] |■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■■ + 0.398 [471] |■■■■■■■■■■ + 0.455 [159] |■■■ + 0.513 [68] |■ + 0.570 [18] | + 0.628 [14] | + 0.686 [21] | + 0.743 [13] | - Latency distribution: - 10% in 0.1805 secs - 25% in 0.2197 secs - 50% in 0.2801 secs - 75% in 0.3129 secs - 90% in 0.3596 secs - 95% in 0.4020 secs - 99% in 0.5457 secs + Latency distribution: + 10% in 0.1805 secs + 25% in 0.2197 secs + 50% in 0.2801 secs + 75% in 0.3129 secs + 90% in 0.3596 secs + 95% in 0.4020 secs + 99% in 0.5457 secs - Details (average, fastest, slowest): - DNS+dialup: 0.0007 secs, 0.1672 secs, 0.7433 secs - DNS-lookup: 0.0000 secs, 0.0000 secs, 0.0000 secs - req write: 0.0001 secs, 0.0000 secs, 0.0045 secs - resp wait: 0.2766 secs, 0.1669 secs, 0.6633 secs - resp read: 0.0002 secs, 0.0000 secs, 0.0065 secs + Details (average, fastest, slowest): + DNS+dialup: 0.0007 secs, 0.1672 secs, 0.7433 secs + DNS-lookup: 0.0000 secs, 0.0000 secs, 0.0000 secs + req write: 0.0001 secs, 0.0000 secs, 0.0045 secs + resp wait: 0.2766 secs, 0.1669 secs, 0.6633 secs + resp read: 0.0002 secs, 0.0000 secs, 0.0065 secs - Status code distribution: - [200] 5424 responses - ``` + Status code distribution: + [200] 5424 responses + ``` - ``` - NAME READY STATUS RESTARTS AGE - autoscale-go-00001-deployment-78cdc67bf4-2w4sk 3/3 Running 0 26s - autoscale-go-00001-deployment-78cdc67bf4-dd2zb 3/3 Running 0 24s - autoscale-go-00001-deployment-78cdc67bf4-pg55p 3/3 Running 0 18s - autoscale-go-00001-deployment-78cdc67bf4-q8bf9 3/3 Running 0 1m - autoscale-go-00001-deployment-78cdc67bf4-thjbq 3/3 Running 0 26s - ``` + ```shell + NAME READY STATUS RESTARTS AGE + autoscale-go-00001-deployment-78cdc67bf4-2w4sk 3/3 Running 0 26s + autoscale-go-00001-deployment-78cdc67bf4-dd2zb 3/3 Running 0 24s + autoscale-go-00001-deployment-78cdc67bf4-pg55p 3/3 Running 0 18s + autoscale-go-00001-deployment-78cdc67bf4-q8bf9 3/3 Running 0 1m + autoscale-go-00001-deployment-78cdc67bf4-thjbq 3/3 Running 0 26s + ``` ## Analysis @@ -125,8 +123,8 @@ A demonstration of the autoscaling capabilities of a Knative Serving Revision. Knative Serving autoscaling is based on the average number of in-flight requests per pod (concurrency). The system has a default [target concurrency of 100](https://github.com/knative/serving/blob/3f00c39e289ed4bfb84019131651c2e4ea660ab5/config/config-autoscaler.yaml#L35-L41) -but [we used 10](service.yaml#L25-L26) for our service. We loaded the service with -50 concurrent requests so the autoscaler created 5 pods +but [we used 10](service.yaml#L25-L26) for our service. We loaded the service +with 50 concurrent requests so the autoscaler created 5 pods (`50 concurrent requests / target of 10 = 5 pods`) #### Panic @@ -139,20 +137,20 @@ autoscaler operates on the shorter, more sensitive panic window. Once the panic conditions are no longer met for 60 seconds, the autoscaler will return to the initial 60 second `stable` window. -``` - | - Panic Target---> +--| 20 - | | - | <------Panic Window - | | - Stable Target---> +-------------------------|--| 10 CONCURRENCY - | | | - | <-----------Stable Window - | | | ---------------------------+-------------------------+--+ 0 -120 60 0 - TIME -``` + ``` + | + Panic Target---> +--| 20 + | | + | <------Panic Window + | | + Stable Target---> +-------------------------|--| 10 CONCURRENCY + | | | + | <-----------Stable Window + | | | + --------------------------+-------------------------+--+ 0 + 120 60 0 + TIME + ``` #### Customization @@ -166,54 +164,54 @@ autoscaler classes built into Knative: Example of a Service scaled on CPU: -```yaml -apiVersion: serving.knative.dev/v1alpha1 -kind: Service -metadata: - name: autoscale-go - namespace: default -spec: - runLatest: - configuration: - revisionTemplate: - metadata: - annotations: - # Standard Kubernetes CPU-based autoscaling. - autoscaling.knative.dev/class: hpa.autoscaling.knative.dev - autoscaling.knative.dev/metric: cpu - spec: - container: - image: gcr.io/knative-samples/autoscale-go:0.1 -``` + ```yaml + apiVersion: serving.knative.dev/v1alpha1 + kind: Service + metadata: + name: autoscale-go + namespace: default + spec: + runLatest: + configuration: + revisionTemplate: + metadata: + annotations: + # Standard Kubernetes CPU-based autoscaling. + autoscaling.knative.dev/class: hpa.autoscaling.knative.dev + autoscaling.knative.dev/metric: cpu + spec: + container: + image: gcr.io/knative-samples/autoscale-go:0.1 + ``` Additionally the autoscaler targets and scaling bounds can be specified in annotations. Example of a Service with custom targets and scale bounds: -```yaml -apiVersion: serving.knative.dev/v1alpha1 -kind: Service -metadata: - name: autoscale-go - namespace: default -spec: - runLatest: - configuration: - revisionTemplate: - metadata: - annotations: - # Knative concurrency-based autoscaling (default). - autoscaling.knative.dev/class: kpa.autoscaling.knative.dev - autoscaling.knative.dev/metric: concurrency - # Target 10 requests in-flight per pod. - autoscaling.knative.dev/target: "10" - # Disable scale to zero with a minScale of 1. - autoscaling.knative.dev/minScale: "1" - # Limit scaling to 100 pods. - autoscaling.knative.dev/maxScale: "100" - spec: - container: - image: gcr.io/knative-samples/autoscale-go:0.1 -``` + ```yaml + apiVersion: serving.knative.dev/v1alpha1 + kind: Service + metadata: + name: autoscale-go + namespace: default + spec: + runLatest: + configuration: + revisionTemplate: + metadata: + annotations: + # Knative concurrency-based autoscaling (default). + autoscaling.knative.dev/class: kpa.autoscaling.knative.dev + autoscaling.knative.dev/metric: concurrency + # Target 10 requests in-flight per pod. + autoscaling.knative.dev/target: "10" + # Disable scale to zero with a minScale of 1. + autoscaling.knative.dev/minScale: "1" + # Limit scaling to 100 pods. + autoscaling.knative.dev/maxScale: "100" + spec: + container: + image: gcr.io/knative-samples/autoscale-go:0.1 + ``` Note: for an `hpa.autoscaling.knative.dev` class service, the `autoscaling.knative.dev/target` specifies the CPU percentage target (default @@ -228,9 +226,9 @@ customization (32 minutes). View the Knative Serving Scaling and Request dashboards (if configured). -``` -kubectl port-forward --namespace knative-monitoring $(kubectl get pods --namespace knative-monitoring --selector=app=grafana --output=jsonpath="{.items..metadata.name}") 3000 -``` + ``` + kubectl port-forward --namespace knative-monitoring $(kubectl get pods --namespace knative-monitoring --selector=app=grafana --output=jsonpath="{.items..metadata.name}") 3000 + ``` ![scale dashboard](scale-dashboard.png) @@ -240,51 +238,52 @@ kubectl port-forward --namespace knative-monitoring $(kubectl get pods --namespa 1. Send 60 seconds of traffic maintaining 100 concurrent requests. - ```shell - hey -z 60s -c 100 \ - -host "autoscale-go.default.example.com" \ - "http://${IP_ADDRESS?}?sleep=100&prime=10000&bloat=5" - ``` + ```shell + hey -z 60s -c 100 \ + -host "autoscale-go.default.example.com" \ + "http://${IP_ADDRESS?}?sleep=100&prime=10000&bloat=5" + ``` 1. Send 60 seconds of traffic maintaining 100 qps with short requests (10 ms). - ```shell - hey -z 60s -q 100 \ - -host "autoscale-go.default.example.com" \ - "http://${IP_ADDRESS?}?sleep=10" - ``` + ```shell + hey -z 60s -q 100 \ + -host "autoscale-go.default.example.com" \ + "http://${IP_ADDRESS?}?sleep=10" + ``` 1. Send 60 seconds of traffic maintaining 100 qps with long requests (1 sec). - ```shell - hey -z 60s -q 100 \ - -host "autoscale-go.default.example.com" \ - "http://${IP_ADDRESS?}?sleep=1000" - ``` + ```shell + hey -z 60s -q 100 \ + -host "autoscale-go.default.example.com" \ + "http://${IP_ADDRESS?}?sleep=1000" + ``` 1. Send 60 seconds of traffic with heavy CPU usage (~1 cpu/sec/request, total 100 cpus). - ```shell - hey -z 60s -q 100 \ - -host "autoscale-go.default.example.com" \ - "http://${IP_ADDRESS?}?prime=40000000" - ``` + ```shell + hey -z 60s -q 100 \ + -host "autoscale-go.default.example.com" \ + "http://${IP_ADDRESS?}?prime=40000000" + ``` 1. Send 60 seconds of traffic with heavy memory usage (1 gb/request, total 5 gb). - ```shell - hey -z 60s -c 5 \ - -host "autoscale-go.default.example.com" \ - "http://${IP_ADDRESS?}?bloat=1000" - ``` + + ```shell + hey -z 60s -c 5 \ + -host "autoscale-go.default.example.com" \ + "http://${IP_ADDRESS?}?bloat=1000" + ``` ## Cleanup -``` -kubectl delete --filename serving/samples/autoscale-go/service.yaml -``` + ``` + kubectl delete --filename docs/serving/samples/autoscale-go/service.yaml + ``` ## Further reading -1. [Autoscaling Developer Documentation](https://github.com/knative/serving/blob/master/docs/scaling/DEVELOPMENT.md) +[Autoscaling Developer Documentation](https://github.com/knative/serving/blob/master/docs/scaling/DEVELOPMENT.md) diff --git a/docs/serving/samples/autoscale-go/_index.md b/docs/serving/samples/autoscale-go/_index.md new file mode 100644 index 000000000..543bde942 --- /dev/null +++ b/docs/serving/samples/autoscale-go/_index.md @@ -0,0 +1,8 @@ +--- +title: "Autoscale Sample App - Go" +linkTitle: "Autoscaling - Go" +weight: 1 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/serving/samples/blue-green-deployment.md b/docs/serving/samples/blue-green-deployment.md index a038beabb..c6130536c 100644 --- a/docs/serving/samples/blue-green-deployment.md +++ b/docs/serving/samples/blue-green-deployment.md @@ -1,4 +1,8 @@ -# Routing and managing traffic with blue/green deployment +--- +title: "Routing and managing traffic with blue/green deployment" +linkTitle: "Routing and managing traffic" +weight: +--- This sample demonstrates updating an application to a new version using a blue/green traffic routing pattern. With Knative, you can safely reroute traffic @@ -11,7 +15,7 @@ You need: - A Kubernetes cluster with [Knative installed](../../install/README.md). - (Optional) - [A custom domain configured](../../serving/using-a-custom-domain.md) for use + [A custom domain configured](../using-a-custom-domain.md) for use with Knative. Note: The source code for the gcr.io/knative-samples/knative-route-demo image @@ -81,7 +85,7 @@ route "blue-green-demo" configured You'll now be able to view the sample app at http://blue-green-demo.default.YOUR_CUSTOM_DOMAIN.com (replace `YOUR_CUSTOM_DOMAIN`) with the -[custom domain](../../serving/using-a-custom-domain.md) you configured for use +[custom domain](../using-a-custom-domain.md) you configured for use with Knative. > Note: If you don't have a custom domain configured for use with Knative, you diff --git a/docs/serving/samples/build-private-repo-go/README.md b/docs/serving/samples/build-private-repo-go/README.md index 20c4af1db..5bc63ae01 100644 --- a/docs/serving/samples/build-private-repo-go/README.md +++ b/docs/serving/samples/build-private-repo-go/README.md @@ -1,4 +1,3 @@ -# Deploying to Knative from a Private GitHub Repo This sample demonstrates: diff --git a/docs/serving/samples/build-private-repo-go/_index.md b/docs/serving/samples/build-private-repo-go/_index.md new file mode 100644 index 000000000..28c7c34a5 --- /dev/null +++ b/docs/serving/samples/build-private-repo-go/_index.md @@ -0,0 +1,8 @@ +--- +title: "Deploying to Knative from a Private GitHub Repo - Go" +linkTitle: "Private GitHub repo - Go" +weight: 1 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/serving/samples/buildpack-app-dotnet/README.md b/docs/serving/samples/buildpack-app-dotnet/README.md index c5aa6799f..363247e63 100644 --- a/docs/serving/samples/buildpack-app-dotnet/README.md +++ b/docs/serving/samples/buildpack-app-dotnet/README.md @@ -1,4 +1,3 @@ -# Buildpack Sample App A sample app that demonstrates using [Cloud Foundry](https://www.cloudfoundry.org/) buildpacks on Knative Serving, @@ -15,7 +14,7 @@ sample app for Cloud Foundry. ## Running This sample uses the -[Buildpack build template](https://github.com/knative/build-templates/blob/master/buildpack/buildpack.yaml) +[Buildpack build template](https://github.com/knative/build-templates/blob/master/buildpacks/cnb.yaml) in the [build-templates](https://github.com/knative/build-templates/) repo. Save a copy of `buildpack.yaml`, then install it: @@ -100,7 +99,7 @@ To clean up the sample service: ```shell # Clean up the serving resources -kubectl delete --filename serving/samples/buildpack-app-dotnet/sample.yaml +kubectl delete --filename docs/serving/samples/buildpack-app-dotnet/sample.yaml # Clean up the build template kubectl delete buildtemplate buildpack ``` diff --git a/docs/serving/samples/buildpack-app-dotnet/_index.md b/docs/serving/samples/buildpack-app-dotnet/_index.md new file mode 100644 index 000000000..8a1cb3c3e --- /dev/null +++ b/docs/serving/samples/buildpack-app-dotnet/_index.md @@ -0,0 +1,8 @@ +--- +title: "Buildpack Sample App - .NET" +linkTitle: "Buildpack app - .NET" +weight: 1 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/serving/samples/buildpack-function-nodejs/README.md b/docs/serving/samples/buildpack-function-nodejs/README.md index 51f27c081..d747bb77c 100644 --- a/docs/serving/samples/buildpack-function-nodejs/README.md +++ b/docs/serving/samples/buildpack-function-nodejs/README.md @@ -1,4 +1,3 @@ -# Buildpack Sample Function A sample function that demonstrates using [Cloud Foundry](https://www.cloudfoundry.org/) buildpacks on Knative Serving, @@ -14,13 +13,13 @@ sample function for riff. ## Running This sample uses the -[Buildpack build template](https://github.com/knative/build-templates/blob/master/buildpack/buildpack.yaml) +[Buildpack build template](https://github.com/knative/build-templates/blob/master/buildpacks/cnb.yaml) from the [build-templates](https://github.com/knative/build-templates/) repo. Save a copy of `buildpack.yaml`, then install it: ```shell -kubectl apply --filename https://raw.githubusercontent.com/knative/build-templates/master/buildpack/buildpack.yaml +kubectl apply --filename https://raw.githubusercontent.com/knative/build-templates/master/buildpacks/cnb.yaml ``` Then you can deploy this to Knative Serving from the root directory via: @@ -98,7 +97,7 @@ To clean up the sample service: ```shell # Clean up the serving resources -kubectl delete --filename serving/samples/buildpack-function-nodejs/sample.yaml +kubectl delete --filename docs/serving/samples/buildpack-function-nodejs/sample.yaml # Clean up the build template kubectl delete buildtemplate buildpack ``` diff --git a/docs/serving/samples/buildpack-function-nodejs/_index.md b/docs/serving/samples/buildpack-function-nodejs/_index.md new file mode 100644 index 000000000..3739587be --- /dev/null +++ b/docs/serving/samples/buildpack-function-nodejs/_index.md @@ -0,0 +1,8 @@ +--- +title: "Buildpack Sample Function - Node.js" +linkTitle: "Buildpack function - Node.js" +weight: 1 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/serving/samples/gitwebhook-go/README.md b/docs/serving/samples/gitwebhook-go/README.md index d26d6e185..98d2cdf1b 100644 --- a/docs/serving/samples/gitwebhook-go/README.md +++ b/docs/serving/samples/gitwebhook-go/README.md @@ -1,4 +1,3 @@ -# GitHub Webhook - Go sample A handler written in Go that demonstrates interacting with GitHub through a webhook. @@ -6,7 +5,7 @@ webhook. ## Prerequisites - A Kubernetes cluster with Knative installed. Follow the - [installation instructions](https://github.com/knative/docs/blob/master/install/README.md) + [installation instructions](../../../install/README.md) if you need to create one. - [Docker](https://www.docker.com) installed and running on your local machine, and a Docker Hub account configured (we'll use it for a container registry). @@ -98,9 +97,9 @@ service "gitwebhook" created 1. Finally, once the service is running, create the webhook from your GitHub repo to the URL for this service. For this to work properly you will need to - [configure a custom domain](https://github.com/knative/docs/blob/master/serving/using-a-custom-domain.md) + [configure a custom domain](../../using-a-custom-domain.md) and - [assign a static IP address](https://github.com/knative/docs/blob/master/serving/gke-assigning-static-ip-address.md). + [assign a static IP address](../../gke-assigning-static-ip-address.md). 1. Retrieve the hostname for this service, using the following command: @@ -119,7 +118,7 @@ service "gitwebhook" created 1. Enter the **Secret** value to be the same as the original base used for `webhookSecret` above (the original value, not the base64 encoded value). 1. Select **Disable** under SSL Validation, unless you've - [enabled SSL](https://github.com/knative/docs/blob/master/serving/using-an-ssl-cert.md). + [enabled SSL](../../using-an-ssl-cert.md). 1. Click **Add webhook** to create the webhook. ## Exploring diff --git a/docs/serving/samples/gitwebhook-go/_index.md b/docs/serving/samples/gitwebhook-go/_index.md new file mode 100644 index 000000000..e44cfcc1d --- /dev/null +++ b/docs/serving/samples/gitwebhook-go/_index.md @@ -0,0 +1,8 @@ +--- +title: "GitHub webhook sample - Go" +linkTitle: "GitHub Webhook - Go" +weight: 1 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/serving/samples/grpc-ping-go/Dockerfile b/docs/serving/samples/grpc-ping-go/Dockerfile index e62768d5f..247747aff 100644 --- a/docs/serving/samples/grpc-ping-go/Dockerfile +++ b/docs/serving/samples/grpc-ping-go/Dockerfile @@ -20,8 +20,8 @@ RUN go get google.golang.org/grpc WORKDIR /go/src/github.com/knative/docs/ ADD . /go/src/github.com/knative/docs/ -RUN CGO_ENABLED=0 go build -tags=grpcping ./serving/samples/grpc-ping-go/ -RUN CGO_ENABLED=0 go build -tags=grpcping ./serving/samples/grpc-ping-go/client +RUN CGO_ENABLED=0 go build -tags=grpcping ./docs/serving/samples/grpc-ping-go/ +RUN CGO_ENABLED=0 go build -tags=grpcping ./docs/serving/samples/grpc-ping-go/client FROM gcr.io/distroless/static diff --git a/docs/serving/samples/grpc-ping-go/README.md b/docs/serving/samples/grpc-ping-go/README.md index 1e1896d62..b4d9ac687 100644 --- a/docs/serving/samples/grpc-ping-go/README.md +++ b/docs/serving/samples/grpc-ping-go/README.md @@ -1,4 +1,3 @@ -# gRPC Ping A simple gRPC server written in Go that you can use for testing. @@ -6,8 +5,9 @@ This sample requires knative/serving 0.4 or later. ## Prerequisites -1. [Install Knative](https://github.com/knative/docs/blob/master/install/README.md) -1. Install [docker](https://www.docker.com/) +1. [Install Knative](../../../install/README.md). + +1. Install [docker](https://www.docker.com/). ## Build and run the gRPC server @@ -17,15 +17,15 @@ First, build and publish the gRPC server to DockerHub (replacing `{username}`): # Build and publish the container, run from the root directory. docker build \ --tag "docker.io/{username}/grpc-ping-go" \ - --file=serving/samples/grpc-ping-go/Dockerfile . -docker push "docker.io/{username}/grpc-ping-go" + --file=docs/serving/samples/grpc-ping-go/Dockerfile . +docker push "${REPO}/docs/serving/samples/grpc-ping-go" ``` Next, replace `{username}` in `sample.yaml` with your DockerHub username, and apply the yaml. ```shell -kubectl apply --filename serving/samples/grpc-ping-go/sample.yaml +kubectl apply --filename docs/serving/samples/grpc-ping-go/sample.yaml ``` ## Use the client to stream messages to the gRPC server diff --git a/docs/serving/samples/grpc-ping-go/_index.md b/docs/serving/samples/grpc-ping-go/_index.md new file mode 100644 index 000000000..755b74e68 --- /dev/null +++ b/docs/serving/samples/grpc-ping-go/_index.md @@ -0,0 +1,8 @@ +--- +title: "gRPC server - Go" +#linkTitle: "" +weight: 1 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/serving/samples/grpc-ping-go/sample.yaml b/docs/serving/samples/grpc-ping-go/sample.yaml index 31f0942f0..d7dddb911 100644 --- a/docs/serving/samples/grpc-ping-go/sample.yaml +++ b/docs/serving/samples/grpc-ping-go/sample.yaml @@ -14,4 +14,3 @@ spec: - name: h2c containerPort: 8080 - diff --git a/docs/serving/samples/hello-world/_index.md b/docs/serving/samples/hello-world/_index.md new file mode 100644 index 000000000..e7844bc95 --- /dev/null +++ b/docs/serving/samples/hello-world/_index.md @@ -0,0 +1,6 @@ +--- +title: "Knative 'Hello World' samples" +linkTitle: "Hello world apps" +weight: 1 +--- + diff --git a/docs/serving/samples/helloworld-csharp/.gitignore b/docs/serving/samples/hello-world/helloworld-csharp/.gitignore similarity index 100% rename from docs/serving/samples/helloworld-csharp/.gitignore rename to docs/serving/samples/hello-world/helloworld-csharp/.gitignore diff --git a/docs/serving/samples/helloworld-csharp/Dockerfile b/docs/serving/samples/hello-world/helloworld-csharp/Dockerfile similarity index 100% rename from docs/serving/samples/helloworld-csharp/Dockerfile rename to docs/serving/samples/hello-world/helloworld-csharp/Dockerfile diff --git a/docs/serving/samples/helloworld-csharp/Program.cs b/docs/serving/samples/hello-world/helloworld-csharp/Program.cs similarity index 100% rename from docs/serving/samples/helloworld-csharp/Program.cs rename to docs/serving/samples/hello-world/helloworld-csharp/Program.cs diff --git a/docs/serving/samples/helloworld-csharp/Properties/launchSettings.json b/docs/serving/samples/hello-world/helloworld-csharp/Properties/launchSettings.json similarity index 100% rename from docs/serving/samples/helloworld-csharp/Properties/launchSettings.json rename to docs/serving/samples/hello-world/helloworld-csharp/Properties/launchSettings.json diff --git a/docs/serving/samples/helloworld-csharp/README.md b/docs/serving/samples/hello-world/helloworld-csharp/README.md similarity index 98% rename from docs/serving/samples/helloworld-csharp/README.md rename to docs/serving/samples/hello-world/helloworld-csharp/README.md index f16f797b2..9e519d336 100644 --- a/docs/serving/samples/helloworld-csharp/README.md +++ b/docs/serving/samples/hello-world/helloworld-csharp/README.md @@ -1,4 +1,3 @@ -# Hello World - .NET Core sample A simple web app written in C# using .NET Core 2.2 that you can use for testing. It reads in an env variable `TARGET` and prints "Hello \${TARGET}!". If TARGET @@ -7,7 +6,7 @@ is not specified, it will use "World" as the TARGET. ## Prerequisites - A Kubernetes cluster with Knative installed. Follow the - [installation instructions](https://github.com/knative/docs/blob/master/install/README.md) + [installation instructions](../../../../install/README.md) if you need to create one. - [Docker](https://www.docker.com) installed and running on your local machine, and a Docker Hub account configured (we'll use it for a container registry). diff --git a/docs/serving/samples/helloworld-csharp/Startup.cs b/docs/serving/samples/hello-world/helloworld-csharp/Startup.cs similarity index 100% rename from docs/serving/samples/helloworld-csharp/Startup.cs rename to docs/serving/samples/hello-world/helloworld-csharp/Startup.cs diff --git a/docs/serving/samples/hello-world/helloworld-csharp/_index.md b/docs/serving/samples/hello-world/helloworld-csharp/_index.md new file mode 100644 index 000000000..f98d54672 --- /dev/null +++ b/docs/serving/samples/hello-world/helloworld-csharp/_index.md @@ -0,0 +1,8 @@ +--- +title: "Hello world - .NET Core" +linkTitle: ".NET" +weight: 1 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/serving/samples/helloworld-csharp/helloworld-csharp.csproj b/docs/serving/samples/hello-world/helloworld-csharp/helloworld-csharp.csproj similarity index 100% rename from docs/serving/samples/helloworld-csharp/helloworld-csharp.csproj rename to docs/serving/samples/hello-world/helloworld-csharp/helloworld-csharp.csproj diff --git a/docs/serving/samples/helloworld-csharp/service.yaml b/docs/serving/samples/hello-world/helloworld-csharp/service.yaml similarity index 100% rename from docs/serving/samples/helloworld-csharp/service.yaml rename to docs/serving/samples/hello-world/helloworld-csharp/service.yaml diff --git a/docs/serving/samples/helloworld-go/Dockerfile b/docs/serving/samples/hello-world/helloworld-go/Dockerfile similarity index 100% rename from docs/serving/samples/helloworld-go/Dockerfile rename to docs/serving/samples/hello-world/helloworld-go/Dockerfile diff --git a/docs/serving/samples/helloworld-go/README.md b/docs/serving/samples/hello-world/helloworld-go/README.md similarity index 98% rename from docs/serving/samples/helloworld-go/README.md rename to docs/serving/samples/hello-world/helloworld-go/README.md index f22a89ce9..ef912ac0d 100644 --- a/docs/serving/samples/helloworld-go/README.md +++ b/docs/serving/samples/hello-world/helloworld-go/README.md @@ -1,4 +1,3 @@ -# Hello World - Go sample A simple web app written in Go that you can use for testing. It reads in an env variable `TARGET` and prints `Hello ${TARGET}!`. If `TARGET` is not specified, @@ -7,7 +6,7 @@ it will use `World` as the `TARGET`. ## Prerequisites - A Kubernetes cluster with Knative installed. Follow the - [installation instructions](https://github.com/knative/docs/blob/master/install/README.md) + [installation instructions](../../../../install/README.md) if you need to create one. - [Docker](https://www.docker.com) installed and running on your local machine, and a Docker Hub account configured (we'll use it for a container registry). diff --git a/docs/serving/samples/hello-world/helloworld-go/_index.md b/docs/serving/samples/hello-world/helloworld-go/_index.md new file mode 100644 index 000000000..7251874db --- /dev/null +++ b/docs/serving/samples/hello-world/helloworld-go/_index.md @@ -0,0 +1,8 @@ +--- +title: "Hello World - Go" +linkTitle: "Go" +weight: 1 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/serving/samples/helloworld-go/helloworld.go b/docs/serving/samples/hello-world/helloworld-go/helloworld.go similarity index 100% rename from docs/serving/samples/helloworld-go/helloworld.go rename to docs/serving/samples/hello-world/helloworld-go/helloworld.go diff --git a/docs/serving/samples/helloworld-go/service.yaml b/docs/serving/samples/hello-world/helloworld-go/service.yaml similarity index 100% rename from docs/serving/samples/helloworld-go/service.yaml rename to docs/serving/samples/hello-world/helloworld-go/service.yaml diff --git a/docs/serving/samples/helloworld-java/.gitignore b/docs/serving/samples/hello-world/helloworld-java/.gitignore similarity index 100% rename from docs/serving/samples/helloworld-java/.gitignore rename to docs/serving/samples/hello-world/helloworld-java/.gitignore diff --git a/docs/serving/samples/helloworld-java/.mvn/wrapper/maven-wrapper.jar b/docs/serving/samples/hello-world/helloworld-java/.mvn/wrapper/maven-wrapper.jar similarity index 100% rename from docs/serving/samples/helloworld-java/.mvn/wrapper/maven-wrapper.jar rename to docs/serving/samples/hello-world/helloworld-java/.mvn/wrapper/maven-wrapper.jar diff --git a/docs/serving/samples/helloworld-java/.mvn/wrapper/maven-wrapper.properties b/docs/serving/samples/hello-world/helloworld-java/.mvn/wrapper/maven-wrapper.properties similarity index 100% rename from docs/serving/samples/helloworld-java/.mvn/wrapper/maven-wrapper.properties rename to docs/serving/samples/hello-world/helloworld-java/.mvn/wrapper/maven-wrapper.properties diff --git a/docs/serving/samples/helloworld-java/Dockerfile b/docs/serving/samples/hello-world/helloworld-java/Dockerfile similarity index 100% rename from docs/serving/samples/helloworld-java/Dockerfile rename to docs/serving/samples/hello-world/helloworld-java/Dockerfile diff --git a/docs/serving/samples/helloworld-java/README.md b/docs/serving/samples/hello-world/helloworld-java/README.md similarity index 98% rename from docs/serving/samples/helloworld-java/README.md rename to docs/serving/samples/hello-world/helloworld-java/README.md index 9550e6957..615ef103c 100644 --- a/docs/serving/samples/helloworld-java/README.md +++ b/docs/serving/samples/hello-world/helloworld-java/README.md @@ -1,4 +1,3 @@ -# Hello World - Spring Boot Java sample A simple web app written in Java using Spring Boot 2.0 that you can use for testing. It reads in an env variable `TARGET` and prints "Hello \${TARGET}!". If @@ -7,7 +6,7 @@ TARGET is not specified, it will use "World" as the TARGET. ## Prerequisites - A Kubernetes cluster with Knative installed. Follow the - [installation instructions](https://github.com/knative/docs/blob/master/install/README.md) + [installation instructions](../../../../install/README.md) if you need to create one. - [Docker](https://www.docker.com) installed and running on your local machine, and a Docker Hub account configured (we'll use it for a container registry). diff --git a/docs/serving/samples/hello-world/helloworld-java/_index.md b/docs/serving/samples/hello-world/helloworld-java/_index.md new file mode 100644 index 000000000..b718207b9 --- /dev/null +++ b/docs/serving/samples/hello-world/helloworld-java/_index.md @@ -0,0 +1,8 @@ +--- +title: "Hello World - Spring Boot Java" +linkTitle: "Java" +weight: 1 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/serving/samples/helloworld-java/helloworld.zip b/docs/serving/samples/hello-world/helloworld-java/helloworld.zip similarity index 100% rename from docs/serving/samples/helloworld-java/helloworld.zip rename to docs/serving/samples/hello-world/helloworld-java/helloworld.zip diff --git a/docs/serving/samples/helloworld-java/mvnw b/docs/serving/samples/hello-world/helloworld-java/mvnw similarity index 100% rename from docs/serving/samples/helloworld-java/mvnw rename to docs/serving/samples/hello-world/helloworld-java/mvnw diff --git a/docs/serving/samples/helloworld-java/mvnw.cmd b/docs/serving/samples/hello-world/helloworld-java/mvnw.cmd similarity index 100% rename from docs/serving/samples/helloworld-java/mvnw.cmd rename to docs/serving/samples/hello-world/helloworld-java/mvnw.cmd diff --git a/docs/serving/samples/helloworld-java/pom.xml b/docs/serving/samples/hello-world/helloworld-java/pom.xml similarity index 100% rename from docs/serving/samples/helloworld-java/pom.xml rename to docs/serving/samples/hello-world/helloworld-java/pom.xml diff --git a/docs/serving/samples/helloworld-java/service.yaml b/docs/serving/samples/hello-world/helloworld-java/service.yaml similarity index 100% rename from docs/serving/samples/helloworld-java/service.yaml rename to docs/serving/samples/hello-world/helloworld-java/service.yaml diff --git a/docs/serving/samples/helloworld-java/src/main/java/com/example/helloworld/HelloworldApplication.java b/docs/serving/samples/hello-world/helloworld-java/src/main/java/com/example/helloworld/HelloworldApplication.java similarity index 100% rename from docs/serving/samples/helloworld-java/src/main/java/com/example/helloworld/HelloworldApplication.java rename to docs/serving/samples/hello-world/helloworld-java/src/main/java/com/example/helloworld/HelloworldApplication.java diff --git a/docs/serving/samples/helloworld-java/src/main/resources/application.properties b/docs/serving/samples/hello-world/helloworld-java/src/main/resources/application.properties similarity index 100% rename from docs/serving/samples/helloworld-java/src/main/resources/application.properties rename to docs/serving/samples/hello-world/helloworld-java/src/main/resources/application.properties diff --git a/docs/serving/samples/helloworld-java/src/test/java/com/example/helloworld/HelloworldApplicationTests.java b/docs/serving/samples/hello-world/helloworld-java/src/test/java/com/example/helloworld/HelloworldApplicationTests.java similarity index 100% rename from docs/serving/samples/helloworld-java/src/test/java/com/example/helloworld/HelloworldApplicationTests.java rename to docs/serving/samples/hello-world/helloworld-java/src/test/java/com/example/helloworld/HelloworldApplicationTests.java diff --git a/docs/serving/samples/helloworld-kotlin/Dockerfile b/docs/serving/samples/hello-world/helloworld-kotlin/Dockerfile similarity index 100% rename from docs/serving/samples/helloworld-kotlin/Dockerfile rename to docs/serving/samples/hello-world/helloworld-kotlin/Dockerfile diff --git a/docs/serving/samples/helloworld-kotlin/README.md b/docs/serving/samples/hello-world/helloworld-kotlin/README.md similarity index 98% rename from docs/serving/samples/helloworld-kotlin/README.md rename to docs/serving/samples/hello-world/helloworld-kotlin/README.md index 26fedb28d..d3236cfa6 100644 --- a/docs/serving/samples/helloworld-kotlin/README.md +++ b/docs/serving/samples/hello-world/helloworld-kotlin/README.md @@ -1,4 +1,3 @@ -# Hello World - Kotlin sample A simple web app written in Kotlin using [Ktor](https://ktor.io/) that you can use for testing. It reads in an env variable `TARGET` and prints "Hello @@ -7,7 +6,7 @@ use for testing. It reads in an env variable `TARGET` and prints "Hello ## Prerequisites - A Kubernetes cluster with Knative installed. Follow the - [installation instructions](https://github.com/knative/docs/blob/master/install/README.md) + [installation instructions](../../../../install/README.md) if you need to create one. - [Docker](https://www.docker.com) installed and running on your local machine, and a Docker Hub account configured (we'll use it for a container registry). diff --git a/docs/serving/samples/hello-world/helloworld-kotlin/_index.md b/docs/serving/samples/hello-world/helloworld-kotlin/_index.md new file mode 100644 index 000000000..b0bc90d7f --- /dev/null +++ b/docs/serving/samples/hello-world/helloworld-kotlin/_index.md @@ -0,0 +1,8 @@ +--- +title: "Hello World - Kotlin" +linkTitle: "Kotlin" +weight: 1 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/serving/samples/helloworld-kotlin/build.gradle b/docs/serving/samples/hello-world/helloworld-kotlin/build.gradle similarity index 100% rename from docs/serving/samples/helloworld-kotlin/build.gradle rename to docs/serving/samples/hello-world/helloworld-kotlin/build.gradle diff --git a/docs/serving/samples/helloworld-kotlin/service.yaml b/docs/serving/samples/hello-world/helloworld-kotlin/service.yaml similarity index 100% rename from docs/serving/samples/helloworld-kotlin/service.yaml rename to docs/serving/samples/hello-world/helloworld-kotlin/service.yaml diff --git a/docs/serving/samples/helloworld-kotlin/src/main/kotlin/com/example/hello/Main.kt b/docs/serving/samples/hello-world/helloworld-kotlin/src/main/kotlin/com/example/hello/Main.kt similarity index 100% rename from docs/serving/samples/helloworld-kotlin/src/main/kotlin/com/example/hello/Main.kt rename to docs/serving/samples/hello-world/helloworld-kotlin/src/main/kotlin/com/example/hello/Main.kt diff --git a/docs/serving/samples/helloworld-nodejs/.gitignore b/docs/serving/samples/hello-world/helloworld-nodejs/.gitignore similarity index 100% rename from docs/serving/samples/helloworld-nodejs/.gitignore rename to docs/serving/samples/hello-world/helloworld-nodejs/.gitignore diff --git a/docs/serving/samples/helloworld-nodejs/Dockerfile b/docs/serving/samples/hello-world/helloworld-nodejs/Dockerfile similarity index 100% rename from docs/serving/samples/helloworld-nodejs/Dockerfile rename to docs/serving/samples/hello-world/helloworld-nodejs/Dockerfile diff --git a/docs/serving/samples/helloworld-nodejs/README.md b/docs/serving/samples/hello-world/helloworld-nodejs/README.md similarity index 97% rename from docs/serving/samples/helloworld-nodejs/README.md rename to docs/serving/samples/hello-world/helloworld-nodejs/README.md index 102b7b612..da2d808ea 100644 --- a/docs/serving/samples/helloworld-nodejs/README.md +++ b/docs/serving/samples/hello-world/helloworld-nodejs/README.md @@ -1,4 +1,3 @@ -# Hello World - Node.js sample A simple web app written in Node.js that you can use for testing. It reads in an env variable `TARGET` and prints "Hello \${TARGET}!". If TARGET is not @@ -7,7 +6,7 @@ specified, it will use "World" as the TARGET. ## Prerequisites - A Kubernetes cluster with Knative installed. Follow the - [installation instructions](https://github.com/knative/docs/blob/master/install/README.md) + [installation instructions](../../../../install/README.md) if you need to create one. - [Docker](https://www.docker.com) installed and running on your local machine, and a Docker Hub account configured (we'll use it for a container registry). @@ -19,7 +18,8 @@ While you can clone all of the code from this directory, hello world apps are generally more useful if you build them step-by-step. The following instructions recreate the source files from this folder. -1. Create a new directory and initalize `npm`. + +1. Create a new directory and initialize `npm`: ```shell npm init diff --git a/docs/serving/samples/hello-world/helloworld-nodejs/_index.md b/docs/serving/samples/hello-world/helloworld-nodejs/_index.md new file mode 100644 index 000000000..366f22a97 --- /dev/null +++ b/docs/serving/samples/hello-world/helloworld-nodejs/_index.md @@ -0,0 +1,8 @@ +--- +title: "Hello World - Node.js" +linkTitle: "Node.js" +weight: 1 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/serving/samples/helloworld-nodejs/index.js b/docs/serving/samples/hello-world/helloworld-nodejs/index.js similarity index 100% rename from docs/serving/samples/helloworld-nodejs/index.js rename to docs/serving/samples/hello-world/helloworld-nodejs/index.js diff --git a/docs/serving/samples/helloworld-nodejs/package-lock.json b/docs/serving/samples/hello-world/helloworld-nodejs/package-lock.json similarity index 100% rename from docs/serving/samples/helloworld-nodejs/package-lock.json rename to docs/serving/samples/hello-world/helloworld-nodejs/package-lock.json diff --git a/docs/serving/samples/helloworld-nodejs/package.json b/docs/serving/samples/hello-world/helloworld-nodejs/package.json similarity index 100% rename from docs/serving/samples/helloworld-nodejs/package.json rename to docs/serving/samples/hello-world/helloworld-nodejs/package.json diff --git a/docs/serving/samples/helloworld-nodejs/service.yaml b/docs/serving/samples/hello-world/helloworld-nodejs/service.yaml similarity index 100% rename from docs/serving/samples/helloworld-nodejs/service.yaml rename to docs/serving/samples/hello-world/helloworld-nodejs/service.yaml diff --git a/docs/serving/samples/helloworld-php/Dockerfile b/docs/serving/samples/hello-world/helloworld-php/Dockerfile similarity index 100% rename from docs/serving/samples/helloworld-php/Dockerfile rename to docs/serving/samples/hello-world/helloworld-php/Dockerfile diff --git a/docs/serving/samples/helloworld-php/README.md b/docs/serving/samples/hello-world/helloworld-php/README.md similarity index 97% rename from docs/serving/samples/helloworld-php/README.md rename to docs/serving/samples/hello-world/helloworld-php/README.md index 1054fdb12..77bb0c9a4 100644 --- a/docs/serving/samples/helloworld-php/README.md +++ b/docs/serving/samples/hello-world/helloworld-php/README.md @@ -1,4 +1,3 @@ -# Hello World - PHP sample A simple web app written in PHP that you can use for testing. It reads in an env variable `TARGET` and prints "Hello \${TARGET}!". If TARGET is not specified, it @@ -7,7 +6,7 @@ will use "World" as the TARGET. ## Prerequisites - A Kubernetes cluster with Knative installed. Follow the - [installation instructions](https://github.com/knative/docs/blob/master/install/README.md) + [installation instructions](../../../../install/README.md) if you need to create one. - [Docker](https://www.docker.com) installed and running on your local machine, and a Docker Hub account configured (we'll use it for a container registry). diff --git a/docs/serving/samples/hello-world/helloworld-php/_index.md b/docs/serving/samples/hello-world/helloworld-php/_index.md new file mode 100644 index 000000000..4d10a3938 --- /dev/null +++ b/docs/serving/samples/hello-world/helloworld-php/_index.md @@ -0,0 +1,8 @@ +--- +title: "Hello World - PHP" +linkTitle: "PHP" +weight: 1 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/serving/samples/helloworld-php/index.php b/docs/serving/samples/hello-world/helloworld-php/index.php similarity index 100% rename from docs/serving/samples/helloworld-php/index.php rename to docs/serving/samples/hello-world/helloworld-php/index.php diff --git a/docs/serving/samples/helloworld-php/service.yaml b/docs/serving/samples/hello-world/helloworld-php/service.yaml similarity index 100% rename from docs/serving/samples/helloworld-php/service.yaml rename to docs/serving/samples/hello-world/helloworld-php/service.yaml diff --git a/docs/serving/samples/hello-world/helloworld-python/Dockerfile b/docs/serving/samples/hello-world/helloworld-python/Dockerfile new file mode 100644 index 000000000..e0bfa7b31 --- /dev/null +++ b/docs/serving/samples/hello-world/helloworld-python/Dockerfile @@ -0,0 +1,18 @@ +# Use the official Python image. +# https://hub.docker.com/_/python +FROM python + +# Copy local code to the container image. +ENV APP_HOME /app +WORKDIR $APP_HOME +COPY . . + +# Install production dependencies. +RUN pip install Flask + +# Service must listen to $PORT environment variable. +# This default value facilitates local development. +ENV PORT 8080 + +# Run the web service on container startup. +CMD ["python", "app.py"] diff --git a/docs/serving/samples/helloworld-python/README.md b/docs/serving/samples/hello-world/helloworld-python/README.md similarity index 97% rename from docs/serving/samples/helloworld-python/README.md rename to docs/serving/samples/hello-world/helloworld-python/README.md index 323f8e11a..ae03045f3 100644 --- a/docs/serving/samples/helloworld-python/README.md +++ b/docs/serving/samples/hello-world/helloworld-python/README.md @@ -1,4 +1,3 @@ -# Hello World - Python sample A simple web app written in Python that you can use for testing. It reads in an env variable `TARGET` and prints "Hello \${TARGET}!". If TARGET is not @@ -7,7 +6,7 @@ specified, it will use "World" as the TARGET. ## Prerequisites - A Kubernetes cluster with Knative installed. Follow the - [installation instructions](https://github.com/knative/docs/blob/master/install/README.md) + [installation instructions](../../../../install/README.md) if you need to create one. - [Docker](https://www.docker.com) installed and running on your local machine, and a Docker Hub account configured (we'll use it for a container registry). diff --git a/docs/serving/samples/hello-world/helloworld-python/_index.md b/docs/serving/samples/hello-world/helloworld-python/_index.md new file mode 100644 index 000000000..ca652936e --- /dev/null +++ b/docs/serving/samples/hello-world/helloworld-python/_index.md @@ -0,0 +1,8 @@ +--- +title: "Hello World - Python" +linkTitle: "Python" +weight: 1 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/serving/samples/helloworld-python/app.py b/docs/serving/samples/hello-world/helloworld-python/app.py similarity index 100% rename from docs/serving/samples/helloworld-python/app.py rename to docs/serving/samples/hello-world/helloworld-python/app.py diff --git a/docs/serving/samples/helloworld-python/service.yaml b/docs/serving/samples/hello-world/helloworld-python/service.yaml similarity index 100% rename from docs/serving/samples/helloworld-python/service.yaml rename to docs/serving/samples/hello-world/helloworld-python/service.yaml diff --git a/docs/serving/samples/helloworld-ruby/Dockerfile b/docs/serving/samples/hello-world/helloworld-ruby/Dockerfile similarity index 100% rename from docs/serving/samples/helloworld-ruby/Dockerfile rename to docs/serving/samples/hello-world/helloworld-ruby/Dockerfile diff --git a/docs/serving/samples/helloworld-ruby/Gemfile b/docs/serving/samples/hello-world/helloworld-ruby/Gemfile similarity index 100% rename from docs/serving/samples/helloworld-ruby/Gemfile rename to docs/serving/samples/hello-world/helloworld-ruby/Gemfile diff --git a/docs/serving/samples/helloworld-ruby/Gemfile.lock b/docs/serving/samples/hello-world/helloworld-ruby/Gemfile.lock similarity index 100% rename from docs/serving/samples/helloworld-ruby/Gemfile.lock rename to docs/serving/samples/hello-world/helloworld-ruby/Gemfile.lock diff --git a/docs/serving/samples/helloworld-ruby/README.md b/docs/serving/samples/hello-world/helloworld-ruby/README.md similarity index 97% rename from docs/serving/samples/helloworld-ruby/README.md rename to docs/serving/samples/hello-world/helloworld-ruby/README.md index 19e6d1deb..7f8b976cd 100644 --- a/docs/serving/samples/helloworld-ruby/README.md +++ b/docs/serving/samples/hello-world/helloworld-ruby/README.md @@ -1,4 +1,3 @@ -# Hello World - Ruby sample A simple web app written in Ruby that you can use for testing. It reads in an env variable `TARGET` and prints "Hello \${TARGET}!". If TARGET is not @@ -7,7 +6,7 @@ specified, it will use "World" as the TARGET. ## Prerequisites - A Kubernetes cluster with Knative installed. Follow the - [installation instructions](https://github.com/knative/docs/blob/master/install/README.md) + [installation instructions](../../../../install/README.md) if you need to create one. - [Docker](https://www.docker.com) installed and running on your local machine, and a Docker Hub account configured (we'll use it for a container registry). diff --git a/docs/serving/samples/hello-world/helloworld-ruby/_index.md b/docs/serving/samples/hello-world/helloworld-ruby/_index.md new file mode 100644 index 000000000..8ba065d53 --- /dev/null +++ b/docs/serving/samples/hello-world/helloworld-ruby/_index.md @@ -0,0 +1,8 @@ +--- +title: "Hello World - Ruby" +linkTitle: "Ruby" +weight: 1 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/serving/samples/helloworld-ruby/app.rb b/docs/serving/samples/hello-world/helloworld-ruby/app.rb similarity index 100% rename from docs/serving/samples/helloworld-ruby/app.rb rename to docs/serving/samples/hello-world/helloworld-ruby/app.rb diff --git a/docs/serving/samples/helloworld-ruby/service.yaml b/docs/serving/samples/hello-world/helloworld-ruby/service.yaml similarity index 100% rename from docs/serving/samples/helloworld-ruby/service.yaml rename to docs/serving/samples/hello-world/helloworld-ruby/service.yaml diff --git a/docs/serving/samples/helloworld-scala/.gitignore b/docs/serving/samples/hello-world/helloworld-scala/.gitignore similarity index 100% rename from docs/serving/samples/helloworld-scala/.gitignore rename to docs/serving/samples/hello-world/helloworld-scala/.gitignore diff --git a/docs/serving/samples/helloworld-scala/README.md b/docs/serving/samples/hello-world/helloworld-scala/README.md similarity index 91% rename from docs/serving/samples/helloworld-scala/README.md rename to docs/serving/samples/hello-world/helloworld-scala/README.md index 8955b85ba..5a152f0b3 100644 --- a/docs/serving/samples/helloworld-scala/README.md +++ b/docs/serving/samples/hello-world/helloworld-scala/README.md @@ -1,4 +1,3 @@ -# Hello World - Scala using Akka HTTP sample A microservice which demonstrates how to get set up and running with Knative Serving when using [Scala](https://scala-lang.org/) and [Akka](https://akka.io/) @@ -9,7 +8,7 @@ to `"Hello World!"`. ## Prerequisites - A Kubernetes cluster - [installation](https://github.com/knative/docs/blob/master/install/README.md) + [installation](../../../../install/README.md) with Knative Serving up and running. - [Docker](https://www.docker.com) installed locally, and running, optionally a Docker Hub account configured or some other Docker Repository installed @@ -41,7 +40,7 @@ docker tag yourreponame/helloworld-scala: dev.local/helloworld-scala: \ - serving/samples/rest-api-go/sample.yaml + envsubst < docs/serving/samples/rest-api-go/sample-template.yaml > \ + docs/serving/samples/rest-api-go/sample.yaml ``` ## Deploy the Service @@ -93,8 +92,9 @@ docker push "${REPO}/rest-api-go" Now that our image is available from the container registry, we can deploy the Knative Serving sample: + ```shell -kubectl apply --filename serving/samples/rest-api-go/sample.yaml +kubectl apply --filename docs/serving/samples/rest-api-go/sample.yaml ``` The above command creates a Knative Service within your Kubernetes cluster in @@ -234,7 +234,7 @@ Response body: `stock price for ticker is ` ## Next Steps The -[traffic splitting example](https://github.com/knative/docs/tree/master/serving/samples/traffic-splitting) +[traffic splitting example](../traffic-splitting/README.md) continues from here to walk through creating new Revisions and splitting traffic between multiple Revisions. @@ -242,6 +242,7 @@ between multiple Revisions. To clean up the sample Service: + ```shell -kubectl delete --filename serving/samples/rest-api-go/sample.yaml +kubectl delete --filename docs/serving/samples/rest-api-go/sample.yaml ``` diff --git a/docs/serving/samples/rest-api-go/_index.md b/docs/serving/samples/rest-api-go/_index.md new file mode 100644 index 000000000..07aeddb92 --- /dev/null +++ b/docs/serving/samples/rest-api-go/_index.md @@ -0,0 +1,8 @@ +--- +title: "Creating a RESTful Service - Go" +linkTitle: "RESTful service - Go" +weight: 1 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/serving/samples/rest-api-go/sample.yaml b/docs/serving/samples/rest-api-go/sample.yaml index 865f662f0..f4b4ff9c5 100644 --- a/docs/serving/samples/rest-api-go/sample.yaml +++ b/docs/serving/samples/rest-api-go/sample.yaml @@ -31,3 +31,4 @@ spec: path: / initialDelaySeconds: 0 periodSeconds: 3 + diff --git a/docs/serving/samples/secrets-go/README.md b/docs/serving/samples/secrets-go/README.md index 7ac80cb40..57855314b 100644 --- a/docs/serving/samples/secrets-go/README.md +++ b/docs/serving/samples/secrets-go/README.md @@ -8,7 +8,7 @@ into a container as a Volume. ## Prerequisites - A Kubernetes cluster with Knative installed. Follow the - [installation instructions](https://github.com/knative/docs/blob/master/install/README.md) + [installation instructions](../../../install/README.md) if you need to create one. - [Docker](https://www.docker.com) installed and running on your local machine, and a Docker Hub account configured (we'll use it for a container registry). diff --git a/docs/serving/samples/secrets-go/service.yaml b/docs/serving/samples/secrets-go/service.yaml index ac780009c..a72854a2f 100644 --- a/docs/serving/samples/secrets-go/service.yaml +++ b/docs/serving/samples/secrets-go/service.yaml @@ -9,7 +9,7 @@ spec: revisionTemplate: spec: container: - image: github.com/knative/docs/serving/samples/secrets-go + image: github.com/knative/docs/docs/serving/samples/secrets-go env: # This directs the Google Cloud SDK to use the identity and project # defined by the Service Account (aka robot) in the JSON file at diff --git a/docs/serving/samples/source-to-url-go/README.md b/docs/serving/samples/source-to-url-go/README.md index 0660130a4..7076f48ba 100644 --- a/docs/serving/samples/source-to-url-go/README.md +++ b/docs/serving/samples/source-to-url-go/README.md @@ -1,4 +1,3 @@ -# Orchestrating a source-to-URL deployment on Kubernetes A Go sample that shows how to use Knative to go from source code in a git repository to a running application with a URL. @@ -12,7 +11,7 @@ deployment. You need: - A Kubernetes cluster with Knative installed. Follow the - [installation instructions](https://github.com/knative/docs/blob/master/install/README.md) + [installation instructions](../../../install/README.md) if you need to create one. - Go installed and configured. This is optional, and only required if you want to run the sample app locally. @@ -40,7 +39,7 @@ In order to push the container that is built from source to Docker Hub, register a secret in Kubernetes for authentication with Docker Hub. There are -[detailed instructions](https://github.com/knative/docs/blob/master/build/auth.md#basic-authentication-docker) +[detailed instructions](../../../build/auth.md#basic-authentication-docker) available, but these are the key steps: 1. Create a new `Secret` manifest, which is used to store your Docker Hub diff --git a/docs/serving/samples/source-to-url-go/_index.md b/docs/serving/samples/source-to-url-go/_index.md new file mode 100644 index 000000000..0fa6e04e0 --- /dev/null +++ b/docs/serving/samples/source-to-url-go/_index.md @@ -0,0 +1,8 @@ +--- +title: "Orchestrating a source-to-URL deployment on Kubernetes - Go" +linkTitle: "Build and deploy - Go" +weight: 1 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/serving/samples/telemetry-go/README.md b/docs/serving/samples/telemetry-go/README.md index 47108c8df..bd3f8d665 100644 --- a/docs/serving/samples/telemetry-go/README.md +++ b/docs/serving/samples/telemetry-go/README.md @@ -1,4 +1,3 @@ -# Telemetry Sample This sample runs a simple web server that makes calls to other in-cluster services and responds to requests with "Hello World!". The purpose of this @@ -10,7 +9,7 @@ dedicated Prometheus instance rather than using the default installation. ## Prerequisites 1. A Kubernetes cluster with - [Knative Serving](https://github.com/knative/docs/blob/master/install/README.md) + [Knative Serving](../../../install/README.md) installed. 2. Check if Knative monitoring components are installed: @@ -26,7 +25,7 @@ kubectl get pods --namespace knative-monitoring 4. Check out the code: ``` -go get -d github.com/knative/docs/serving/samples/telemetry-go +go get -d github.com/knative/docs/docs/serving/samples/telemetry-go ``` ## Setup @@ -53,22 +52,22 @@ Google Cloud Project and to enable the ``` docker build \ - --tag "${REPO}/serving/samples/telemetry-go" \ - --file=serving/samples/telemetry-go/Dockerfile . + --tag "${REPO}/docs/serving/samples/telemetry-go" \ + --file=docs/serving/samples/telemetry-go/Dockerfile . ``` 4. Push your container to a container registry: ``` -docker push "${REPO}/serving/samples/telemetry-go" +docker push "${REPO}/docs/serving/samples/telemetry-go" ``` 5. Replace the image reference path with our published image path in the - configuration file (`serving/samples/telemetry-go/sample.yaml`): + configuration file (`docs/serving/samples/telemetry-go/sample.yaml`): - Manually replace: - `image: github.com/knative/docs/serving/samples/telemetry-go` with - `image: /serving/samples/telemetry-go` + `image: github.com/knative/docs/docs/serving/samples/telemetry-go` with + `image: /docs/serving/samples/telemetry-go` Or @@ -77,7 +76,7 @@ docker push "${REPO}/serving/samples/telemetry-go" ``` - perl -pi -e "s@github.com/knative/docs@${REPO}@g" serving/samples/telemetry-go/sample.yaml + perl -pi -e "s@github.com/knative/docs@${REPO}@g" docs/serving/samples/telemetry-go/sample.yaml ``` ## Deploy the Service @@ -85,7 +84,7 @@ docker push "${REPO}/serving/samples/telemetry-go" Deploy this application to Knative Serving: ``` -kubectl apply --filename serving/samples/telemetry-go/ +kubectl apply --filename docs/serving/samples/telemetry-go/ ``` ## Explore the Service @@ -214,5 +213,5 @@ Then browse to http://localhost:9090. To clean up the sample service: ``` -kubectl delete --filename serving/samples/telemetry-go/ +kubectl delete --filename docs/serving/samples/telemetry-go/ ``` diff --git a/docs/serving/samples/telemetry-go/_index.md b/docs/serving/samples/telemetry-go/_index.md new file mode 100644 index 000000000..824f7d607 --- /dev/null +++ b/docs/serving/samples/telemetry-go/_index.md @@ -0,0 +1,8 @@ +--- +title: "Observability: Monitoring, logging, and tracing sample - Go" +linkTitle: "Observability - Go" +weight: 1 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/serving/samples/telemetry-go/sample.yaml b/docs/serving/samples/telemetry-go/sample.yaml index 6e5ab149f..470217076 100644 --- a/docs/serving/samples/telemetry-go/sample.yaml +++ b/docs/serving/samples/telemetry-go/sample.yaml @@ -28,4 +28,4 @@ spec: container: # This is the Go import path for the binary to containerize # and substitute here. - image: github.com/knative/docs/serving/samples/telemetry-go + image: github.com/knative/docs/docs/serving/samples/telemetry-go diff --git a/docs/serving/samples/thumbnailer-go/README.md b/docs/serving/samples/thumbnailer-go/README.md index 156cddf99..485378d69 100644 --- a/docs/serving/samples/thumbnailer-go/README.md +++ b/docs/serving/samples/thumbnailer-go/README.md @@ -1,4 +1,3 @@ -# Thumbnailer External Dependencies Demo This is a walk-through example that demonstrates deploying a dockerized application that accesses external dependencies to Knative Serving. In this demo diff --git a/docs/serving/samples/thumbnailer-go/_index.md b/docs/serving/samples/thumbnailer-go/_index.md new file mode 100644 index 000000000..241c1d0c8 --- /dev/null +++ b/docs/serving/samples/thumbnailer-go/_index.md @@ -0,0 +1,8 @@ +--- +title: "Thumbnailer External Dependencies Demo - Go" +linkTitle: "Deploy, build, and serve - Go" +weight: 1 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/serving/samples/traffic-splitting/README.md b/docs/serving/samples/traffic-splitting/README.md index 93170b130..f42ce0bd3 100644 --- a/docs/serving/samples/traffic-splitting/README.md +++ b/docs/serving/samples/traffic-splitting/README.md @@ -1,165 +1,137 @@ -# Simple Traffic Splitting Between Revisions -This samples builds off of the [Creating a RESTful Service](../rest-api-go) sample -to illustrate updating a Service to create a new Revision as well as splitting traffic -between the two created Revisions. +This samples builds off the [Creating a RESTful Service](../rest-api-go) sample +to illustrate applying a revision, then using that revision for manual traffic +splitting. ## Prerequisites -1. Complete the Service creation steps in [Creating a RESTful Service](../rest-api-go). -1. Move into the docs directory: - -```shell -cd $GOPATH/src/github.com/knative/docs -``` - -## Updating to Release Mode - -The service was originally created with a mode of `runLatest`. In `runLatest` -mode, the service serves the latest Revision that is ready to handle incoming -traffic. To split traffic between multiple Revisions, the Service mode will need -to be changed to `release` mode. The `release` mode differs from `runLatest` in that -it requires a `revisions` list. The `revisions` list accepts 1 or 2 Revisions -that will be served by the base domain of the service. When 2 Revisions are -present in the list a `rolloutPercent` parameter specifies the percentage of -traffic to send to each Revision. - -This first step will update the Service to release mode with a single Revision. - -1. To populate the `revisions` list the name of the created Revision is required. -The command below captures the names of all created Revisions as an array so it -can be substituted it into the YAML. - -```shell -REVISIONS=($(kubectl get revision -l "serving.knative.dev/service=stock-service-example" -o \ -jsonpath="{.items[*].metadata.name}")) -echo ${REVISIONS[*]} -``` - -2. The `release_sample.yaml` is setup in this directory to allow enable substituting the -Revision name into the file with the `envsubst` utility. Executing the -command below will update the Service to release mode with the queried Revision name. - -- Note: The command below expects `$REPO` to still be exported. See - [RESTful Service Setup](https://github.com/knative/docs/tree/master/serving/samples/rest-api-go#setup) to set it. - -```shell -CURRENT=${REVISIONS[0]} \ -envsubst < serving/samples/traffic-splitting/release_sample.yaml \ -| kubectl apply --filename - -``` - -3. The `spec` of the Service should now show `release` with the Revision name -retrieved above. - -```shell -kubectl get ksvc stock-service-example --output yaml -``` +1. [Creating a RESTful Service](../rest-api-go). ## Updating the Service -This section describes how to create a new Revision by updating your Service. +This section describes how to create an revision by deploying a new +configuration. -A new Revision is created every time a value in the `revisionTemplate` section of -the Service `spec` is updated. The `updated_sample.yaml` in this folder changes -the environment variable `RESOURCE` from `stock` to `share`. Applying this -change will result in a new Revision. +1. Replace the image reference path with our published image path in the + configuration files + (`docs/serving/samples/traffic-splitting/updated_configuration.yaml`: -For comparison, you can diff the `release_sample.yaml` with the `updated_sample.yaml`. + - Manually replace: + `image: github.com/knative/docs/docs/serving/samples/rest-api-go` with + `image: /docs/serving/samples/rest-api-go` -```shell -diff serving/samples/traffic-splitting/release_sample.yaml \ -serving/samples/traffic-splitting/updated_sample.yaml + Or + + - Use run this command: + + ``` + perl -pi -e "s@github.com/knative/docs@${REPO}@g" docs/serving/samples/rest-api-go/updated_configuration.yaml + ``` + +2. Deploy the new configuration to update the `RESOURCE` environment variable + from `stock` to `share`: + +``` +kubectl apply --filename docs/serving/samples/traffic-splitting/updated_configuration.yaml ``` -1. Execute the command below to update the environment variable in the Service - resulting in a new Revision. +3. Once deployed, traffic will shift to the new revision automatically. Verify + the deployment by checking the route status: -```shell -CURRENT=${REVISIONS[0]} \ -envsubst < serving/samples/traffic-splitting/updated_sample.yaml \ -| kubectl apply --filename - +``` +kubectl get route --output yaml ``` -2. Since we are using a `release` service, traffic will _not_ shift to the new - Revision automatically. However, it will be available from the subdomain - `latest`. This can be verified through the Service status: +4. When the new route is ready, you can access the new endpoints: The hostname + and IP address can be found in the same manner as the + [Creating a RESTful Service](../rest-api-go) sample: -```shell -kubectl get ksvc stock-service-example --output yaml +``` +export SERVICE_HOST=`kubectl get route stock-route-example --output jsonpath="{.status.domain}"` + +# In Knative 0.2.x and prior versions, the `knative-ingressgateway` service was used instead of `istio-ingressgateway`. +INGRESSGATEWAY=knative-ingressgateway + +# The use of `knative-ingressgateway` is deprecated in Knative v0.3.x. +# Use `istio-ingressgateway` instead, since `knative-ingressgateway` +# will be removed in Knative v0.4. +if kubectl get configmap config-istio -n knative-serving &> /dev/null; then + INGRESSGATEWAY=istio-ingressgateway +fi + +export SERVICE_IP=`kubectl get svc $INGRESSGATEWAY --namespace istio-system \ + --output jsonpath="{.status.loadBalancer.ingress[*].ip}"` ``` -3. The readiness of the Service can be verified through the Service Conditions. - When the Service conditions report it is ready again, you can access the new - Revision using the same method as found in the [previous sample](../rest-api-go/README.md#access-the-service) - by prefixing the Service hostname with `latest.`. +- Make a request to the index endpoint: -```shell -curl --header "Host:latest.${SERVICE_HOSTNAME}" http://${INGRESS_IP} +``` +curl --header "Host:$SERVICE_HOST" http://${SERVICE_IP} ``` -- Hitting the top domain (or `current.`) will hit the Revision at the first - index of the `revisions` list: +Response body: `Welcome to the share app!` -```shell -curl --header "Host:${SERVICE_HOSTNAME}" http://${INGRESS_IP} -curl --header "Host:current.${SERVICE_HOSTNAME}" http://${INGRESS_IP} +- Make a request to the `/share` endpoint: + +``` +curl --header "Host:$SERVICE_HOST" http://${SERVICE_IP}/share ``` -## Traffic Splitting +Response body: `share ticker not found!, require /share/{ticker}` -Updating the service to split traffic between the two revisions is done by -placing a second revision in of the `revisions` list and specifying a `rolloutPercent`. -The `rolloutPercent` is the percentage of traffic to send to the second element in -the list. When the Service is Ready the traffic will be split as desired for the -base domain, and a subdomain of `candidate` will be available pointing to the -second Revision. +- Make a request to the `/share` endpoint with a `ticker` parameter: -1. Get the latest list of revisions by executing the command below: - -```shell -REVISIONS=($(kubectl get revision -l "serving.knative.dev/service=stock-service-example" --output \ -jsonpath="{.items[*].metadata.name}")) -echo ${REVISIONS[*]} +``` +curl --header "Host:$SERVICE_HOST" http://${SERVICE_IP}/share/ ``` -2. Update the `revisions` list in - `serving/samples/traffic-splitting/split_sample.yaml`. A `rolloutPercent` of - 50 has already been specified, but can be changed if desired by editing the - `split_sample.yaml` file. +Response body: `share price for ticker is ` +## Manual Traffic Splitting -```shell -CURRENT=${REVISIONS[0]} CANDIDATE=${REVISIONS[1]} \ -envsubst < serving/samples/traffic-splitting/split_sample.yaml \ -| kubectl apply --filename - +This section describes how to manually split traffic to specific revisions. + +1. Get your revisions names via: + +``` +kubectl get revisions ``` -3. Verify the deployment by checking the service status: - -```shell -kubectl get ksvc --output yaml +``` +NAME AGE +stock-configuration-example-00001 11m +stock-configuration-example-00002 4m ``` -4. Once updated, `curl` requests to the base domain should result in responses split evenly between `Welcome to the share app!` and -`Welcome to the stock app!`. +2. Update the `traffic` list in `docs/serving/samples/rest-api-go/sample.yaml` as: -```shell -curl --header "Host:${SERVICE_HOSTNAME}" http://${INGRESS_IP} +```yaml +traffic: + - revisionName: + percent: 50 + - revisionName: + percent: 50 ``` -5. Much like the `current` and `latest` subdomains there should now be a -`candidate` subdomain that should return `Welcome to the share app!` as it hits -the second index of the `revisions` list. +3. Deploy your traffic revision: -```shell -curl --header "Host:candidate.${SERVICE_HOSTNAME}" http://${INGRESS_IP} ``` +kubectl apply --filename docs/serving/samples/rest-api-go/sample.yaml +``` + +4. Verify the deployment by checking the route status: + +``` +kubectl get route --output yaml +``` + +Once updated, you can make `curl` requests to the API using either `stock` or +`share` endpoints. ## Clean Up To clean up the sample service: -```shell -kubectl delete --filename serving/samples/traffic-splitting/split_sample.yaml +``` +kubectl delete --filename docs/serving/samples/traffic-splitting/updated_configuration.yaml ``` diff --git a/docs/serving/samples/traffic-splitting/_index.md b/docs/serving/samples/traffic-splitting/_index.md new file mode 100644 index 000000000..f0c2fdec3 --- /dev/null +++ b/docs/serving/samples/traffic-splitting/_index.md @@ -0,0 +1,8 @@ +--- +title: "Simple Traffic Splitting Between Revisions" +linkTitle: "Traffic splitting" +weight: 1 +type: "docs" +--- + +{{% readfile file="README.md" relative="true" markdown="true" %}} diff --git a/docs/serving/samples/traffic-splitting/updated_configuration.yaml b/docs/serving/samples/traffic-splitting/updated_configuration.yaml index 3ee206409..53242cf70 100644 --- a/docs/serving/samples/traffic-splitting/updated_configuration.yaml +++ b/docs/serving/samples/traffic-splitting/updated_configuration.yaml @@ -1,4 +1,4 @@ -# Copyright 2019 The Knative Authors +# Copyright 2018 The Knative Authors # # Licensed under the Apache License, Version 2.0 (the "License"); # you may not use this file except in compliance with the License. @@ -13,23 +13,25 @@ # limitations under the License. apiVersion: serving.knative.dev/v1alpha1 -kind: Service +kind: Configuration metadata: - name: stock-service-example + name: stock-configuration-example namespace: default spec: - release: - revisions: ["${CURRENT}"] - configuration: - revisionTemplate: - spec: - container: - image: ${REPO}/rest-api-go - env: - - name: RESOURCE - value: stock - readinessProbe: - httpGet: - path: / - initialDelaySeconds: 0 - periodSeconds: 3 + revisionTemplate: + metadata: + labels: + knative.dev/type: container + spec: + container: + # This is the Go import path for the binary to containerize + # and substitute here. + image: github.com/knative/docs/docs/serving/samples/rest-api-go + env: + - name: RESOURCE + value: share + readinessProbe: + httpGet: + path: / + initialDelaySeconds: 3 + periodSeconds: 3 diff --git a/docs/serving/setting-up-a-logging-plugin.md b/docs/serving/setting-up-a-logging-plugin.md index d75cebb67..5609d1d5b 100644 --- a/docs/serving/setting-up-a-logging-plugin.md +++ b/docs/serving/setting-up-a-logging-plugin.md @@ -1,4 +1,8 @@ -# Setting Up A Logging Plugin +--- +title: "Setting up a logging plugin" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 50 +--- Knative allows cluster operators to use different backends for their logging needs. This document describes how to change these settings. Knative currently @@ -31,7 +35,8 @@ collecting `stdout/stderr` logs from the containers: in [200-fluentd.yaml](https://github.com/knative/serving/blob/master/config/monitoring/logging/elasticsearch/200-fluentd.yaml) with the Fluentd image including the desired Fluentd output plugin. See - [here](fluentd/README.md) for the requirements of Flunetd image on Knative. + [here](./fluentd-requirements.md) for the requirements of Flunetd + image on Knative. ### Configure the Sidecar for log files under /var/log @@ -79,7 +84,7 @@ the Elasticsearch and Kibana services. Knative provides this sample: kubectl apply --recursive --filename third_party/config/monitoring/logging/elasticsearch ``` -See [here](/serving/installing-logging-metrics-traces.md) for deploying the +See [here](./installing-logging-metrics-traces.md) for deploying the whole Knative monitoring components. ## Uninstalling diff --git a/docs/serving/fluentd/stackdriver/Dockerfile b/docs/serving/stackdriver/Dockerfile similarity index 100% rename from docs/serving/fluentd/stackdriver/Dockerfile rename to docs/serving/stackdriver/Dockerfile diff --git a/docs/serving/using-a-custom-domain.md b/docs/serving/using-a-custom-domain.md index f17196473..d41b328e2 100644 --- a/docs/serving/using-a-custom-domain.md +++ b/docs/serving/using-a-custom-domain.md @@ -1,4 +1,8 @@ -# Setting up a custom domain +--- +title: "Setting up a custom domain" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 55 +--- By default, Knative Serving routes use `example.com` as the default domain. The fully qualified domain name for a route by default is @@ -77,7 +81,7 @@ You can also apply an updated domain configuration: > deployed services and routes. Deploy an app (for example, -[`helloworld-go`](./samples/helloworld-go/README.md)), to your cluster as +[`helloworld-go`](./samples/hello-world/helloworld-go/README.md)), to your cluster as normal. You can check the customized domain in Knative Route "helloworld-go" with the following command: @@ -140,7 +144,7 @@ Follow these steps to make your domain publicly accessible: ### Set static IP for Knative Gateway You might want to -[set a static IP for your Knative gateway](gke-assigning-static-ip-address.md), +[set a static IP for your Knative gateway](./gke-assigning-static-ip-address.md), so that the gateway IP does not change each time your cluster is restarted. ### Update your DNS records diff --git a/docs/serving/using-an-ssl-cert.md b/docs/serving/using-an-ssl-cert.md index 5755d8258..abed71690 100644 --- a/docs/serving/using-an-ssl-cert.md +++ b/docs/serving/using-an-ssl-cert.md @@ -1,4 +1,8 @@ -# Configuring HTTPS with a custom certificate +--- +title: "Configuring HTTPS with a custom certificate" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 60 +--- If you already have an SSL/TLS certificate for your domain you can follow the steps below to configure Knative to use your certificate and enable HTTPS @@ -124,12 +128,12 @@ hosting provider. Knative currently only works with the `DNS01` challenge type for LetsEncrypt, which is only supported by a -[small number of DNS providers through cert-manager](http://docs.cert-manager.io/en/latest/reference/issuers/acme/dns01.html?highlight=DNS#supported-dns01-providers). +[small number of DNS providers through cert-manager](http://docs.cert-manager.io/en/latest/tasks/acme/configuring-dns01/index.html?highlight=supported%20DNS01%20providers#supported-dns01-providers). Instructions for configuring cert-manager are provided for the following DNS hosts: -- [Google Cloud DNS](using-cert-manager-on-gcp.md) +- [Google Cloud DNS](./using-cert-manager-on-gcp.md) --- diff --git a/docs/serving/using-cert-manager-on-gcp.md b/docs/serving/using-cert-manager-on-gcp.md index 59b549c9c..1d859434d 100644 --- a/docs/serving/using-cert-manager-on-gcp.md +++ b/docs/serving/using-cert-manager-on-gcp.md @@ -1,8 +1,12 @@ -# Configuring Knative and CertManager for Google Cloud DNS +--- +title: "Configuring Knative and CertManager for Google Cloud DNS" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 65 +--- These instructions assume you have already setup a Knative cluster and installed cert-manager into your cluster. For more information, see -[using an SSL certificate](using-an-ssl-cert.md#install-cert-manager). They also +[using an SSL certificate](./using-an-ssl-cert.md#install-cert-manager). They also assume you have already set up your managed zone with Cloud DNS as part of configuring the domain to map to your IP address. diff --git a/docs/serving/using-external-dns-on-gcp.md b/docs/serving/using-external-dns-on-gcp.md index f4c09f484..aea391f50 100644 --- a/docs/serving/using-external-dns-on-gcp.md +++ b/docs/serving/using-external-dns-on-gcp.md @@ -1,4 +1,8 @@ -# Using ExternalDNS on Google Cloud Platform to automate DNS setup +--- +title: "Using ExternalDNS on Google Cloud Platform to automate DNS setup" +#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" +weight: 70 +--- [ExternalDNS](https://github.com/kubernetes-incubator/external-dns) is a tool that synchronizes exposed Kubernetes Services and Ingresses with DNS providers. @@ -112,7 +116,7 @@ permission to get the credential secret can access your Cloud DNS. ## Set up Knative 1. Follow the - [instruction](https://github.com/knative/docs/blob/master/install/README.md) + [instruction](../install/README.md) to install Knative on your cluster. 1. Configure Knative to use your custom domain. diff --git a/hack/gen-api-reference-docs.sh b/hack/gen-api-reference-docs.sh index 9bfdfbfae..eb16aba64 100755 --- a/hack/gen-api-reference-docs.sh +++ b/hack/gen-api-reference-docs.sh @@ -179,7 +179,8 @@ main() { "${KNATIVE_EVENTING_SOURCES_OUT_FILE}" "${knative_eventing_sources_root}" log "SUCCESS: Generated docs written to ${out_dir}/." - log "Copy the files in reference/ directory to knative/docs." + log "Opening the ${out_dir}/ directory. You can now copy these API files" + log "from ${out_dir}/, into the 'docs/reference/' directory of knative/docs." if command -v xdg-open >/dev/null; then xdg-open "${out_dir}/" elif command -v open >/dev/null; then diff --git a/search.md b/search.md new file mode 100644 index 000000000..e3690fd5a --- /dev/null +++ b/search.md @@ -0,0 +1,6 @@ +--- +title: Search Results +layout: search + +--- +