diff --git a/docs/serving/cluster-local-route.md b/docs/serving/cluster-local-route.md deleted file mode 100644 index 656ba2d72f3..00000000000 --- a/docs/serving/cluster-local-route.md +++ /dev/null @@ -1,75 +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 Knative service to only be available on the cluster-local network (and -not on the public Internet), you can apply the -`networking.knative.dev/visibility=cluster-local` label to the Knative service, route or -Kubernetes service object. - -To label the Knative service: - -```shell -kubectl label kservice ${KSVC_NAME} networking.knative.dev/visibility=cluster-local -``` - -To label a route when the route is used directly without a Knative service: - -```shell -kubectl label route ${ROUTE_NAME} networking.knative.dev/visibility=cluster-local -``` - -To label a Kubernetes service: - -```shell -kubectl label service ${SERVICE_NAME} networking.knative.dev/visibility=cluster-local -``` - -By labeling the Kubernetes service it allows you to restrict visibility in a more -fine-grained way. See [subroutes](./using-subroutes.md) for information about -tagged routes. - -For example, you can deploy the [Hello World sample](./samples/hello-world/helloworld-go/README.md) -and then convert it to be an cluster-local service by labeling the service: - -```shell -kubectl label kservice helloworld-go networking.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 kservice 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/creating-domain-mappings.md b/docs/serving/creating-domain-mappings.md index a8246075ab8..97a8167981e 100644 --- a/docs/serving/creating-domain-mappings.md +++ b/docs/serving/creating-domain-mappings.md @@ -5,23 +5,21 @@ weight: 64 type: "docs" --- -Knative Services are automatically given a default domain name based on the +Knative services are automatically given a default domain name based on the cluster configuration, e.g. "mysvc.mynamespace.mydomain". You can also map a -single custom domain name that you own to a specific Knative Service using the -Domain Mapping feature, if enabled. +single custom domain name that you own to a specific Knative service using the +domain mapping feature, if enabled. -For example, if you own the "example.org" domain name, and configure its DNS -to reference your Knative cluster, you can use the DomainMapping feature to -have this domain be served by a Knative Service. +For example, if you own the `example.org` domain name, and configure its DNS +to reference your Knative cluster, you can use domain mapping to +have this domain be served by a Knative service. ## Before you begin -1. You need to enable the DomainMapping feature (and a supported Knative - Ingress implementation) to use it. - See [Install optional Serving extensions](../install/install-extensions.md#install-optional-serving-extensions). -1. To map a custom domain to a Knative Service, you must first [create a Knative -Service](../serving/services/creating-services). -1. You will need a Domain Name to map, and the ability to change its DNS to +1. You need to enable the domain mapping feature, as well as a supported Knative + Ingress implementation to use it. See [Install optional Serving extensions](../install/install-extensions.md#install-optional-serving-extensions). +1. [Create a Knative service](../serving/services/creating-services) that you can map a domain to. +1. You will need a domain name to map, and the ability to change its DNS to point to your Knative Cluster. The details of this step are dependant on your domain registrar. @@ -43,34 +41,32 @@ multiple Domain Mappings to map multiple domains and subdomains. ### Procedure 1. Create a new file named `domainmapping.yaml` containing the following information. - ```yaml - apiVersion: serving.knative.dev/v1alpha1 - kind: DomainMapping - metadata: - name: example.org - namespace: default - spec: - ref: - name: helloworld-go - kind: Service - apiVersion: serving.knative.dev/v1 - ``` - * `name`(metadata): The domain name you wish to map to the Knative Service. - * `namespace`: The namespace that both the DomainMapping and Knative Service use. - * `name`(ref): The Knative Service which should be used to service requests - for the custom domain name. You can also map to other targets as long as - they conform to the Addressable contract and their resolved URL is of the - form `{name}.{namespace}.{clusterdomain}` where `{name}` and `{namespace}` - are the name and namespace of a Kubernetes service, and `{clusterdomain}` - is the cluster domain. Objects conforming to this contract include Knative - Services and Routes, and Kubernetes Services. + + ```yaml + apiVersion: serving.knative.dev/v1alpha1 + kind: DomainMapping + metadata: + name: example.org + namespace: default + spec: + ref: + name: helloworld-go + kind: Service + apiVersion: serving.knative.dev/v1 + ``` + * `name`(metadata): The domain name you wish to map to the Knative service. + * `namespace`: The namespace that both domain mapping and the Knative service use. + * `name`(ref): The Knative service which should be used to service requests + for the custom domain name. You can also map to other targets as long as + they conform to the Addressable contract and their resolved URL is of the form `{name}.{namespace}.{clusterdomain}` where `{name}` and `{namespace}`are the name and namespace of a Kubernetes service, and `{clusterdomain}`is the cluster domain. Objects conforming to this contract include Knative services and Routes, and Kubernetes services. 1. From the directory where the new `domainmapping.yaml` file was created, deploy the domain mapping by applying the `domainmapping.yaml` file. - ``` - kubectl apply --filename domainmapping.yaml - ``` -1. You will also need to point the "example.org" domain name at the IP + ``` + kubectl apply -f domainmapping.yaml + ``` + +1. You will also need to point the `example.org` domain name at the IP address of your Knative cluster. Details of this step differ depending on your domain registrar. diff --git a/docs/serving/knative-kubernetes-services.md b/docs/serving/knative-kubernetes-services.md index 9c0d3018364..41caff1d0fa 100644 --- a/docs/serving/knative-kubernetes-services.md +++ b/docs/serving/knative-kubernetes-services.md @@ -1,7 +1,6 @@ --- -title: "Knative Kubernetes Services" -#linkTitle: "OPTIONAL_ALTERNATE_NAV_TITLE" -weight: 9 +title: "Kubernetes services" +weight: 03 type: "docs" --- diff --git a/docs/serving/services/_index.md b/docs/serving/services/_index.md index 141bd81629e..678c542f377 100755 --- a/docs/serving/services/_index.md +++ b/docs/serving/services/_index.md @@ -1,6 +1,7 @@ --- -title: "Knative Services" -linkTitle: "Services" -weight: 10 +title: "Knative services" +weight: 02 type: "docs" --- + +Knative services are used to deploy an application. Each Knative service is defined by a route and a configuration, which have the same name as the service. The configuration and route are created by the service controller, and their configuration is derived from the configuration of the service. Each time the configuration is updated, a new revision is created. Revisions are immutable snapshots of a particular configuration, and use underlying Kubernetes resources to scale the number of pods based on traffic. diff --git a/docs/serving/services/creating-services.md b/docs/serving/services/creating-services.md index 5e3a1d77a76..9b158bc4601 100644 --- a/docs/serving/services/creating-services.md +++ b/docs/serving/services/creating-services.md @@ -1,61 +1,56 @@ --- title: "Creating Knative services" -weight: 10 +linkTitle: "Creating a service" +weight: 02 type: "docs" --- -Knative Services are used to deploy an application. Each Knative Service is defined by a Route and a Configuration, which have the same name as the Service, contained in a YAML file. Every time the Configuration is updated, a new Revision is created. +To create an application using Knative, you must 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. -Knative Service Revisions 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/). +This guide uses the [Hello World sample app in Go](../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. -## Before you begin - -To create a Knative Service, you will need: -* A Kubernetes cluster with [Knative installed](https://knative.dev/docs/install/index.html). -* [Custom domains](https://knative.dev/docs/serving/using-a-custom-domain/) set up for Knative Services. - -## 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: +The Hello World sample app works as follows: 1. Reads an environment variable `TARGET`. 2. Prints `Hello ${TARGET}!`. If `TARGET` is not defined, it will use `World` as the `TARGET`. +## Prerequisites + +To create a Knative service, you will need: +* A Kubernetes cluster with [Knative Serving installed](../../install). +* [Custom domains](../using-a-custom-domain/) set up for Knative services. + ### Procedure -1. Create a new file named `service.yaml` containing the following information. - ```yaml - apiVersion: serving.knative.dev/v1 - kind: Service - metadata: - name: helloworld-go - namespace: default - spec: - template: +1. Create a new file named `service.yaml` containing the following information: + + ```yaml + apiVersion: serving.knative.dev/v1 + kind: Service + metadata: + name: helloworld-go + namespace: default spec: - containers: - - image: gcr.io/knative-samples/helloworld-go - env: - - name: TARGET - value: "Go Sample v1" - ``` - * `apiVersion`: The current Knative version. - * `name`(metadata): The name of the application. - * `namespace`: The namespace that the application will use. - * `image`: The URL to the image of the application. - * `name`(env): The environment variable printed out by the sample application. - - > Note: If you’re deploying an image of your own app, update the name of the app and the URL of the image accordingly. + template: + spec: + containers: + - image: gcr.io/knative-samples/helloworld-go + env: + - name: TARGET + value: "Go Sample v1" + ``` + * `apiVersion`: The current Knative version. + * `name`(metadata): The name of the application. + * `namespace`: The namespace that the application will use. + * `image`: The URL of the image container. + * `name`(env): The environment variable printed out by the sample application. + + **NOTE:** If you’re deploying an image of your own app, update the name of the app and the URL of the image accordingly. 1. From the directory where the new `service.yaml` file was created, deploy the application by applying the `service.yaml` file. - ``` - kubectl apply --filename service.yaml - ``` + + ``` + kubectl apply -f service.yaml + ``` Now that your app has been deployed, Knative will perform the following steps: @@ -63,14 +58,14 @@ Now that your app has been deployed, Knative will perform the following steps: * 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. -## Modifying Knative Services +## 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. The `serving.knative.dev/service` label on the Route and Configuration must also 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. -## What's next? +## Next steps -* For more information about the Knative Service object, see the [Resource Types](https://github.com/knative/serving/blob/main/docs/spec/overview.md#service) documentation. -* For more information about getting started with deploying a Knative application, see the [Getting Started with App Deployment](https://knative.dev/docs/serving/getting-started-knative-app/) documentation. +* To get started with deploying a Knative application, see the [Getting Started with App Deployment](../getting-started-knative-app/) documentation. +* For more information about the Knative Service object, see the [Resource Types](https://github.com/knative/specs/blob/main/specs/serving/overview.md) documentation. diff --git a/docs/serving/services/deployment.md b/docs/serving/services/deployment.md index ddb3e492196..b4facf61124 100644 --- a/docs/serving/services/deployment.md +++ b/docs/serving/services/deployment.md @@ -1,14 +1,14 @@ --- title: "Modifying the Deployment Config Map" linkTitle: "Deployment Configuration" -weight: 03 +weight: 10 type: "docs" --- The `config-deployment` ConfigMap is located in the `knative-serving` namespace. This ConfigMap, known as the Deployment ConfigMap, contains settings that determine how Kubernetes `Deployment` resources, that back Knative services, are configured. -## Accessing the Deployment ConfigMap +## Accessing the Deployment ConfigMap To view the current Deployment ConfigMap: diff --git a/docs/serving/services/private-services.md b/docs/serving/services/private-services.md new file mode 100644 index 00000000000..bd5d485b4dc --- /dev/null +++ b/docs/serving/services/private-services.md @@ -0,0 +1,75 @@ +--- +title: "Creating a private service" +linkTitle: "Configuring private services" +weight: 03 +type: "docs" +aliases: + - /docs/serving/cluster-local-route +--- + +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. + +While this is useful for services that need to be accessible from outside of the +cluster, frequently you may be building a back-end service which should not be +available from outside of the cluster. + +Knative provides three ways to enable private services which are only available +inside the cluster: + +1. To make all services private, change the default domain to + `svc.cluster.local` by + [editing the `config-domain` ConfigMap](../using-a-custom-domain.md). This + changes all services deployed through Knative to only be published to the + cluster. +1. To make an individual service private, the service or route can be + labelled so that it is not published to the external gateway. +1. Use [custom domain mappings](../creating-domain-mappings). + +## Label a service to be cluster-local only + +To configure a Knative service to only be available on the cluster-local network, and not on the public internet, you can apply the +`networking.knative.dev/visibility=cluster-local` label to a Knative service, a route or a Kubernetes service object. + +- To label a Knative service: + + ```shell + kubectl label kservice ${KSVC_NAME} networking.knative.dev/visibility=cluster-local + ``` + + By labeling the Kubernetes service you can restrict visibility in a more + fine-grained way. See [subroutes](../using-subroutes.md) for information about + tagged routes. + +- To label a route when the route is used directly without a Knative service: + + ```shell + kubectl label route ${ROUTE_NAME} networking.knative.dev/visibility=cluster-local + ``` + +- To label a Kubernetes service: + + ```shell + kubectl label service ${SERVICE_NAME} networking.knative.dev/visibility=cluster-local + ``` + +### Example + +You can deploy the [Hello World sample](../samples/hello-world/helloworld-go/) and then convert it to be an cluster-local service by labelling the service: + +```shell +kubectl label kservice helloworld-go networking.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 kservice 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/services/using-a-custom-domain-per-service.md b/docs/serving/services/using-a-custom-domain-per-service.md new file mode 100644 index 00000000000..79882f4e46e --- /dev/null +++ b/docs/serving/services/using-a-custom-domain-per-service.md @@ -0,0 +1,61 @@ +--- +title: "Setting up a custom domain per Service" +weight: 04 +type: "docs" +aliases: + - /docs/serving/using-a-custom-domain-per-service +--- + +By default, Knative uses the `{route}.{namespace}.{default-domain}` fully qualified domain name for services, where `default-domain` is `example.com`. + +You can change the `default-domain` by [Setting up a custom domain](../using-a-custom-domain). You can also set a custom domain per service, by using a custom FQDN for a service, or by using [custom domain mapping](../creating-domain-mappings/). + +## Procedure + +1. Edit the `domainTemplate` entry on the `config-network` configuration: + + ```shell + kubectl edit cm config-network --namespace knative-serving + ``` + + Replace the `domainTemplate` with the following (the spaces must be respected): + + ```yaml + [...] + data: + [...] + domainTemplate: |- + {{if index .Annotations "custom-hostname" -}} + {{- index .Annotations "custom-hostname" -}} + {{else -}} + {{- .Name}}.{{.Namespace -}} + {{end -}} + .{{.Domain}} + ``` + + Save and close your editor. + +1. In a service definition, add the `custom-hostname` annotation: + + ```yaml + apiVersion: serving.knative.dev/v1 + kind: Service + metadata: + name: hello-world + annotations: + # the Service FQDN will become hello-world.{default-domain} + custom-hostname: hello-world + spec: + [...] + ``` + + Apply your changes. + +1. Verify that the service was created with the specified hostname: + + ```shell + kubectl get ksvc hello-world + + NAME URL LATESTCREATED LATESTREADY READY REASON + hello-world http://hello-world.example.com hello-world-nfqh2 hello-world-nfqh2 True + ``` diff --git a/docs/serving/using-a-custom-domain-per-service.md b/docs/serving/using-a-custom-domain-per-service.md deleted file mode 100644 index 2d12fcdaefe..00000000000 --- a/docs/serving/using-a-custom-domain-per-service.md +++ /dev/null @@ -1,66 +0,0 @@ - ---- -title: "Setting up a custom domain per Service" -weight: 55 -type: "docs" ---- - -By default, Knative uses the `{route}.{namespace}.{default-domain}` fully qualified domain name for the Service, where `default-domain` is `example.com`. You are able to change the `default-domain` following the [Setting up a custom domain](./using-a-custom-domain.md) guide. - -This guide documents the process to use a custom FQDN for a Service, like `my-service.example.com`, created by [@bsideup](https://bsideup.github.io/posts/knative_custom_domains/). - -> There is currently no official process to set up a custom domain per Service. The topic is being discussed [here](https://github.com/knative/serving/issues/2985). - -## Edit using kubectl - -1. Edit the `domainTemplate` entry on the `config-network` configuration. You can find more information about it [here](https://github.com/knative/serving/blob/main/config/core/configmaps/network.yaml#L89): - - ```shell - kubectl edit cm config-network --namespace knative-serving - ``` - - Replace the `domainTemplate` with the following (the spaces must be respected): - - ```yaml - [...] - data: - [...] - domainTemplate: |- - {{if index .Annotations "custom-hostname" -}} - {{- index .Annotations "custom-hostname" -}} - {{else -}} - {{- .Name}}.{{.Namespace -}} - {{end -}} - .{{.Domain}} - ``` - - Save and close your editor. - -## Edit the Service - -1. In a Service definition, add the `custom-hostname` annotation: - - ```yaml - apiVersion: serving.knative.dev/v1 - kind: Service - metadata: - name: hello-world - annotations: - # the Service FQDN will become hello-world.{default-domain} - custom-hostname: hello-world - spec: - [...] - ``` - - Apply your changes. - -## Verify the changes - -1. Verify that the Service was created with the specified hostname: - - ```shell - kubectl get ksvc hello-world - - NAME URL LATESTCREATED LATESTREADY READY REASON - hello-world http://hello-world.example.com hello-world-nfqh2 hello-world-nfqh2 True - ```