From bf05f32466ca8f1c09e0208bf3e1ed6769597778 Mon Sep 17 00:00:00 2001 From: abrennan Date: Fri, 8 Nov 2019 12:11:51 -0600 Subject: [PATCH 1/2] Created new Knative Services section --- docs/serving/cluster-local-route.md | 65 ------ docs/serving/getting-started-knative-app.md | 136 ------------ docs/serving/using-knative-services.md | 232 ++++++++++++++++++++ 3 files changed, 232 insertions(+), 201 deletions(-) delete mode 100644 docs/serving/cluster-local-route.md delete mode 100644 docs/serving/getting-started-knative-app.md create mode 100644 docs/serving/using-knative-services.md diff --git a/docs/serving/cluster-local-route.md b/docs/serving/cluster-local-route.md deleted file mode 100644 index 18064082bfa..00000000000 --- a/docs/serving/cluster-local-route.md +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: "Creating a private cluster-local service" -linkTitle: "Configuring cluster-local services" -weight: 20 -type: "docs" ---- - -By default services deployed through Knative are published to an external IP -address, making them public services on a public IP address and with a -[public URL](./using-a-custom-domain.md). - -While this is useful for services that need to be accessible from outside of the -cluster, frequently you may be building a backend service which should not be -available off-cluster. - -Knative provides two ways to enable private services which are only available -inside the cluster: - -1. To make all services only cluster-local, change the default domain to - `svc.cluster.local` by - [editing the `config-domain` config map](./using-a-custom-domain.md). This - will change all services deployed through Knative to only be published to the - cluster, none will be available off-cluster. -1. To make an individual service cluster-local, the service or route can be - labeled in such a way to prevent it from getting published to the external - gateway. - -## Label a service to be cluster-local - -To configure a KService to only be available on the cluster-local network (and -not on the public Internet), you can apply the -`serving.knative.dev/visibility=cluster-local` label to the KService or Route -object. - -To label the KService: - -```shell -kubectl label kservice ${KSVC_NAME} serving.knative.dev/visibility=cluster-local -``` - -To label a route: - -```shell -kubectl label route ${ROUTE_NAME} serving.knative.dev/visibility=cluster-local -``` - -For example, you can deploy the [Hello World sample](./samples/helloworld-go) -and then convert it to be an cluster-local service by labeling the service: - -```shell -kubectl label kservice helloworld-go serving.knative.dev/visibility=cluster-local -``` - -You can then verify that the change has been made by verifying the URL for the -helloworld-go service: - -```shell -kubectl get ksvc helloworld-go - -NAME URL LATESTCREATED LATESTREADY READY REASON -helloworld-go http://helloworld-go.default.svc.cluster.local helloworld-go-2bz5l helloworld-go-2bz5l True -``` - -The service returns the a URL with the `svc.cluster.local` domain, indicating -the service is only available in the cluster local network. diff --git a/docs/serving/getting-started-knative-app.md b/docs/serving/getting-started-knative-app.md deleted file mode 100644 index 0cdc022ead3..00000000000 --- a/docs/serving/getting-started-knative-app.md +++ /dev/null @@ -1,136 +0,0 @@ ---- -title: "Getting Started with App Deployment" -linkTitle: "Getting started" -weight: 01 -type: "docs" -aliases: - - /docs/install/getting-started-knative-app/ ---- - -This guide shows you how to deploy an app using Knative, then interact with it -using cURL requests. - -## Before you begin - -You need: - -- A Kubernetes cluster with [Knative installed](../install/README.md). -- An image of the app that you'd like to deploy available on a container - registry. The image of the sample app used in this guide is available on - Google Container Registry. - -## Sample application - -This guide uses the -[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/), -[Google Container Registry](https://cloud.google.com/container-registry/docs/pushing-and-pulling), -or another container image registry. - -The Hello World sample app reads in an `env` variable, `TARGET`, from the -configuration `.yaml` file, then prints "Hello World: \${TARGET}!". If `TARGET` -isn't defined, it will print "NOT SPECIFIED". - -## Configuring your deployment - -To deploy an app using Knative, you need a configuration `.yaml` file that -defines a Service. For more information about the Service object, see the -[Resource Types documentation](https://github.com/knative/serving/blob/master/docs/spec/overview.md#service). - -This configuration file specifies metadata about the application, points to the -hosted image of the app for deployment, and allows the deployment to be -configured. For more information about what configuration options are available, -see the -[Serving spec documentation](https://github.com/knative/serving/blob/master/docs/spec/spec.md). - -Create a new file named `service.yaml`, then copy and paste the following -content into it: - -```yaml -apiVersion: serving.knative.dev/v1 # Current version of Knative -kind: Service -metadata: - name: helloworld-go # The name of the app - namespace: default # The namespace the app will use -spec: - template: - spec: - containers: - - image: gcr.io/knative-samples/helloworld-go # The URL to the image of the app - env: - - name: TARGET # The environment variable printed out by the sample app - value: "Go Sample v1" -``` - -If you want to deploy the sample app, leave the config file as-is. If you're -deploying an image of your own app, update the name of the app and the URL of -the image accordingly. - -## Deploying your app - -From the directory where the new `service.yaml` file was created, apply the -configuration: - -```bash -kubectl apply --filename service.yaml -``` - -Now that your service is created, Knative will perform the following steps: - -- Create a new immutable revision for this version of the app. -- Perform network programming to create a route, ingress, service, and load - balancer for your app. -- Automatically scale your pods up and down based on traffic, including to zero - active pods. - -### Interacting with your app - -To see if your app has been deployed successfully, you need the URL created by Knative. - -1. To find the URL for your service, enter: - - ```shell - kubectl get ksvc helloworld-go - ``` - - The command will return the following: - - ```shell - NAME URL LATESTCREATED LATESTREADY READY REASON - helloworld-go http://helloworld-go.default.34.83.80.117.xip.io helloworld-go-96dtk helloworld-go-96dtk True - ``` - - > Note: If your URL includes `example.com` then consult the setup instructions for - > configuring DNS (e.g. with `xip.io`), or [using a Custom Domain](../serving/using-a-custom-domain.md). - - If you changed the name from `helloworld-go` to something else when creating - the `.yaml` file, replace `helloworld-go` in the above commands with the name - you entered. - -1. Now you can make a request to your app and see the results. Replace - the URL with the one returned by the command in the previous step. - - ```shell - # curl http://helloworld-go.default.34.83.80.117.xip.io - Hello World: Go Sample v1! - ``` - - If you deployed your own app, you might want to customize this cURL request - to interact with your application. - - It can take a few seconds for Knative to scale up your application and return - a response. - - > Note: Add `-v` option to get more detail if the `curl` command failed. - -You've successfully deployed your first application using Knative! - -## Cleaning up - -To remove the sample app from your cluster, delete the service record: - -```shell -kubectl delete --filename service.yaml -``` diff --git a/docs/serving/using-knative-services.md b/docs/serving/using-knative-services.md new file mode 100644 index 00000000000..cfc43418655 --- /dev/null +++ b/docs/serving/using-knative-services.md @@ -0,0 +1,232 @@ +--- +title: "Using Knative Services" +weight: 01 +linkTitle: "Using Knative Services" +type: "docs" +--- + +Knative services are used to deploy an application. Knative Services attempt to model a more logical definition of a Service or Application. To achieve this, Services use the concept of Revisions which are each backed by a deployment with 2 Kubernetes Services. + +For more information about Kubernetes Services, see the [Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/service/). + +Each Knative Service is defined by a Route and a Configuration, which have the same name as the Service, contained in a YAML file. + +## Before you begin + +To use Knative Services, you will need: +* A Kubernetes cluster with [Knative installed](https://knative.dev/docs/install/index.html). + +## Creating a Knative Service +To create an application, you need to create a YAML file that defines a Knative Service. +This YAML file specifies metadata about the application, points to the hosted image of the app and allows the Service to be configured. + +This guide uses the [Hello World sample app in Go](https://knative.dev/docs/serving/samples/hello-world/helloworld-go) to demonstrate the structure of a Service YAML file and the basic workflow for deploying an app. These steps can be adapted for your own application if you have an image of it available on Docker Hub, Google Container Registry, or another container image registry. + +The Hello World sample app does the following: +1. Reads an environment variable, `TARGET`, from the configuration .yaml file +1. Prints `Hello World: \${TARGET}!`. If `TARGET` is not defined, it will print `NOT SPECIFIED`. + +### Procedure + +1. Create a new file named `service.yaml` containing the following information. + +```yml +apiVersion: serving.knative.dev/v1 # (1) +kind: Service +metadata: + name: helloworld-go # (2) + namespace: default # (3) +spec: + template: + spec: + containers: + - image: gcr.io/knative-samples/helloworld-go # (4) + env: + - name: TARGET # (5) + value: "Go Sample v1" +``` +**(1)** Current version of Knative +**(2)** The name of the app +**(3)** The namespace the app will use +**(4)** The URL to the image of the app +**(5)** The environment variable printed out by the sample app + +> Note: If you’re deploying an image of your own app, update the name of the app and the URL of the image accordingly. + +## Creating a private cluster-local Service +By default services deployed through Knative are published to an external IP +address, making them public services on a public IP address and with a +[public URL](./using-a-custom-domain.md). + +While this is useful for services that need to be accessible from outside of the +cluster, frequently you may be building a backend service which should not be +available off-cluster. + +Knative provides two ways to enable private services which are only available +inside the cluster: + +1. To make all services only available only from within the cluster, change the default domain to + `svc.cluster.local` by + [editing the `config-domain` config map](./using-a-custom-domain.md). This + will change all services deployed through Knative to only be published to the + cluster, none will be available off-cluster. +1. To make an individual service cluster-local, the service or route can be + labeled in such a way to prevent it from getting published to the external + gateway. + +### Label a service to be cluster-local + +To configure a Service to only be available on the cluster-local network (and +not on the public Internet), you can apply the +`serving.knative.dev/visibility=cluster-local` label to the Service object. + +To label the Service: + +```shell +kubectl label kservice ${KSVC_NAME} serving.knative.dev/visibility=cluster-local +``` + +To label a route: + +```shell +kubectl label route ${ROUTE_NAME} serving.knative.dev/visibility=cluster-local +``` + +For example, you can deploy the [Hello World sample](./samples/helloworld-go) +and then convert it to be an cluster-local service by labeling the service: + +```shell +kubectl label kservice helloworld-go serving.knative.dev/visibility=cluster-local +``` + +You can then verify that the change has been made by verifying the URL for the +helloworld-go service: + +```shell +kubectl get ksvc helloworld-go + +NAME URL LATESTCREATED LATESTREADY READY REASON +helloworld-go http://helloworld-go.default.svc.cluster.local helloworld-go-2bz5l helloworld-go-2bz5l True +``` + +The service returns the a URL with the `svc.cluster.local` domain, indicating +the service is only available in the cluster local network. + +## Deploying an application using Knative Services + +To deploy an application, you must apply the `service.yaml` file. + +### Procedure +1. Navigate to the directory where the `service.yaml` file is contained. +2. Deploy the application by applying the `service.yaml` file. + ``` + kubectl apply --filename service.yaml + ``` + +Now that service has been created and the application has been deployed, Knative will create a new immutable revision for this version of the application. + +Knative will also perform network programming to create a route, ingress, service, and load balancer for your application, and will automatically scale your pods up and down based on traffic, including inactive pods. + +## Interacting with your app + +To see if your application has been deployed successfully, you need the host URL and IP +address created by Knative. + +> Note: If your cluster is new, it can take some time before the Service is +assigned an external IP address. + +1. To find the IP address for your Service, enter: + + ```shell + INGRESSGATEWAY=knative-ingressgateway + if kubectl get configmap config-istio -n knative-serving &> /dev/null; then + INGRESSGATEWAY=istio-ingressgateway + fi + + kubectl get svc $INGRESSGATEWAY --namespace istio-system + ``` + +The command will return something similar to this: + +```shell + NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE + istio-ingressgateway LoadBalancer 10.23.247.74 35.203.155.229 80:32380/TCP,443:32390/TCP,32400:32400/TCP 2d +```` + +Take note of the `EXTERNAL-IP` address. + +You can also export the IP address as a variable with the following command: + +```shell + export IP_ADDRESS=$(kubectl get svc $INGRESSGATEWAY --namespace istio-system --output 'jsonpath={.status.loadBalancer.ingress[0].ip}') +``` + +> Note: If you use minikube or a baremetal cluster that has no external load +> balancer, the `EXTERNAL-IP` field is shown as ``. You need to use +> `NodeIP` and `NodePort` to interact your app instead. To get your app's +> `NodeIP` and `NodePort`, enter the following command: + +```shell + export IP_ADDRESS=$(kubectl get node --output 'jsonpath={.items[0].status.addresses[0].address}'):$(kubectl get svc $INGRESSGATEWAY --namespace istio-system --output 'jsonpath={.spec.ports[?(@.port==80)].nodePort}') +``` + +1. To find the host URL for your service, enter: + + ```shell + kubectl get route helloworld-go --output=custom-columns=NAME:.metadata.name,URL:.status.url + ``` + + The command will return the following: + + ```shell + NAME URL + helloworld-go http://helloworld-go.default.example.com + ``` + + > Note: By default, Knative uses the `example.com` domain. To configure a + > custom DNS domain, see + > [Using a Custom Domain](../serving/using-a-custom-domain.md). + + If you changed the name from `helloworld-go` to something else when creating + the `.yaml` file, replace `helloworld-go` in the above commands with the name + you entered. + +1. Now you can make a request to your app and see the results. Replace + `IP_ADDRESS` with the `EXTERNAL-IP` you wrote down, and replace + `helloworld-go.default.example.com` with the domain returned in the previous + step. + + ```shell + curl -H "Host: helloworld-go.default.example.com" http://${IP_ADDRESS} + Hello World: Go Sample v1! + ``` + > Note: If you have configured a domain associated with your IP address, you do not need to inject the host header in this step. + + If you deployed your own app, you might want to customize this cURL request + to interact with your application. + + It can take a few seconds for Knative to scale up your application and return + a response. + + > Note: Add `-v` option to get more detail if the `curl` command failed. + +You've successfully deployed your first application using Knative! + +## Cleaning up + +To remove the sample app from your cluster, delete the service record: + +```shell +kubectl delete --filename service.yaml +``` + +## Modifying Knative Services +Any changes to specifications, metadata labels or metadata annotations for a Service must be copied to the Route and Configuration owned by that Service. + +In addition, the `serving.knative.dev/service` label on the Route and Configuration must be set to the name of the Service. Any additional labels or annotations on the Route and Configuration not specified above must be removed. + +The Service updates its `status` fields based on the corresponding `status` value for the owned Route and Configuration. +The Service must include conditions of`RoutesReady` and `ConfigurationsReady` in addition to the generic `Ready` condition. Other conditions can also be present. + +## Additional resources +* For more information about the Knative Service object, see the [Resource Types documentation](https://github.com/knative/serving/blob/master/docs/spec/overview.md#service). From 03009c3cd6b9db25df4287c1c1aadc04af7d4d36 Mon Sep 17 00:00:00 2001 From: abrennan Date: Mon, 11 Nov 2019 13:25:56 -0600 Subject: [PATCH 2/2] Fixed link for autoscaling docs --- docs/serving/README.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/docs/serving/README.md b/docs/serving/README.md index ebaf1e9abca..c13b5a3867a 100644 --- a/docs/serving/README.md +++ b/docs/serving/README.md @@ -36,7 +36,7 @@ serverless workload behaves on the cluster: are immutable objects and can be retained for as long as useful. Knative Serving Revisions can be automatically scaled up and down according to incoming traffic. See - [Configuring the Autoscaler](./configuring-the-autoscaler.md) for more + [Configuring the Autoscaler](./configuring-autoscaling.md) for more information. ![Diagram that displays how the Serving resources coordinate with each other.](https://github.com/knative/serving/raw/master/docs/spec/images/object_model.png) @@ -82,5 +82,3 @@ in the Knative Serving repository. See the [Knative Serving Issues](https://github.com/knative/serving/issues) page for a full list of known issues. - -