mirror of https://github.com/knative/docs.git
Developer guide mkdocs (#3646)
* [WIP] Developer guide mkdocs * cleanup for service docs * updated headings, cleanup * updated headings, cleanup
This commit is contained in:
Ashleigh Brennan
GitHub
parent
15a8c25668
commit
94a51fdda7
|
|
@ -0,0 +1,3 @@
|
|||
# Developer guide
|
||||
|
||||
The following topics provide information for developers about how to complete administration tasks and use development tools for a Knative cluster.
|
||||
|
|
@ -0,0 +1,18 @@
|
|||
# About Knative Services
|
||||
|
||||
Knative Services are used to deploy an application. To create an application using Knative, you must create a YAML file that defines a Service. This YAML file specifies metadata about the application, points to the hosted image of the app, and allows the Service to be configured.
|
||||
|
||||
Each Service is defined by a Route and a Configuration that have the same name as the service. The Configuration and Route are created by the service controller, and derive their configuration 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Additional resources
|
||||
|
||||
* For more information about the Knative Service object, see the [Resource Types](https://github.com/knative/specs/blob/main/specs/serving/overview.md) documentation.
|
||||
|
|
@ -0,0 +1,28 @@
|
|||
# Configure resource requests and limits
|
||||
|
||||
You can configure resource limits and requests, specifically for CPU and memory, for individual Knative services.
|
||||
|
||||
The following example shows how you can set the `requests` and `limits` fields for a service:
|
||||
|
||||
```yaml
|
||||
apiVersion: serving.knative.dev/v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: example-service
|
||||
namespace: default
|
||||
spec:
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
- image: docker.io/user/example-app
|
||||
resources:
|
||||
requests:
|
||||
cpu: 100m
|
||||
memory: 640M
|
||||
limits:
|
||||
cpu: 1
|
||||
```
|
||||
|
||||
## Additional resources
|
||||
|
||||
* For more information requests and limits for Kubernetes resources, see [Managing Resources for Containers](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/).
|
||||
|
|
@ -0,0 +1,50 @@
|
|||
# Creating a Service
|
||||
|
||||
You can create a Knative service by applying a YAML file or using the `kn service create` CLI command.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
To create a Knative service, you will need:
|
||||
|
||||
* A Kubernetes cluster with [Knative Serving installed](../../../../admin/install).
|
||||
* Optional: To use the `kn service create` command, you must [install the `kn` CLI](../../../../client/install-kn).
|
||||
|
||||
## Procedure
|
||||
|
||||
!!! tip
|
||||
|
||||
The following commands create a `helloworld-go` sample service. You can modify these commands, including the container image URL, to deploy your own application as a Knative service.
|
||||
|
||||
Create a sample service:
|
||||
|
||||
=== "Apply YAML"
|
||||
|
||||
```yaml
|
||||
kubectl apply -f - <<EOF
|
||||
apiVersion: serving.knative.dev/v1
|
||||
kind: Service
|
||||
metadata:
|
||||
name: helloworld-go
|
||||
namespace: default
|
||||
spec:
|
||||
template:
|
||||
spec:
|
||||
containers:
|
||||
- image: gcr.io/knative-samples/helloworld-go
|
||||
env:
|
||||
- name: TARGET
|
||||
value: "Go Sample v1"
|
||||
EOF
|
||||
```
|
||||
|
||||
=== "kn CLI"
|
||||
|
||||
```
|
||||
kn service create helloworld-go --image gcr.io/knative-samples/helloworld-go
|
||||
```
|
||||
|
||||
After the service has been created, Knative performs the following tasks:
|
||||
|
||||
* Creates a new immutable revision for this version of the app.
|
||||
* Performs network programming to create a route, ingress, service, and load balancer for your app.
|
||||
* Automatically scales your pods up and down based on traffic, including to zero active pods.
|
||||
|
|
@ -0,0 +1,60 @@
|
|||
# Configuring private Services
|
||||
|
||||
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.
|
||||
|
||||
Knative provides three ways to enable private services which are only available
|
||||
inside the cluster:
|
||||
|
||||
1. To make all Knative Services private, change the default domain to
|
||||
`svc.cluster.local` by [editing the `config-domain` ConfigMap](../../../../serving/using-a-custom-domain). 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 with `networking.knative.dev/visibility=cluster-local` so that it is not published to the external gateway.
|
||||
1. Use [custom domain mappings](../../../../serving/creating-domain-mappings).
|
||||
|
||||
## Using the cluster-local label
|
||||
|
||||
To configure a Knative Service so that it is only 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](../../../../serving/using-subroutes) 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](../../../../serving/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.
|
||||
|
|
@ -1,9 +0,0 @@
|
|||
---
|
||||
title: "Knative services"
|
||||
weight: 02
|
||||
type: "docs"
|
||||
---
|
||||
|
||||
# Knative services
|
||||
|
||||
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.
|
||||
|
|
@ -1,73 +0,0 @@
|
|||
---
|
||||
title: "Creating Knative services"
|
||||
linkTitle: "Creating a service"
|
||||
weight: 02
|
||||
type: "docs"
|
||||
---
|
||||
|
||||
# Creating Knative services
|
||||
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
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:
|
||||
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 -f service.yaml
|
||||
```
|
||||
|
||||
Now that your app has been deployed, 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.
|
||||
|
||||
## 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.
|
||||
|
||||
## Next steps
|
||||
|
||||
* 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.
|
||||
|
|
@ -1,77 +0,0 @@
|
|||
---
|
||||
title: "Creating a private service"
|
||||
linkTitle: "Configuring private services"
|
||||
weight: 03
|
||||
type: "docs"
|
||||
aliases:
|
||||
- /docs/serving/cluster-local-route
|
||||
---
|
||||
|
||||
# Creating a private 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.
|
||||
|
||||
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.
|
||||
15
mkdocs.yml
15
mkdocs.yml
|
|
@ -47,13 +47,17 @@ nav:
|
|||
- Logging: admin/collecting-logs/README.md
|
||||
- Metrics: admin/collecting-metrics/README.md
|
||||
- Uninstalling Knative: admin/install/uninstall.md
|
||||
- Developer guide:
|
||||
- Overview: developer/README.md
|
||||
- Knative Serving:
|
||||
- Services:
|
||||
- About Knative Services: developer/serving/services/README.md
|
||||
- Creating a Service: developer/serving/services/creating-services.md
|
||||
- Configure resource requests and limits: developer/serving/services/configure-requests-limits-services.md
|
||||
- Configuring private Services: developer/serving/services/private-services.md
|
||||
- Serving Component:
|
||||
- Overview: serving/README.md
|
||||
- Developer Topics:
|
||||
- Knative services:
|
||||
- Overview: serving/services/README.md
|
||||
- Creating a service: serving/services/creating-services.md
|
||||
- Configuring private services: serving/services/private-services.md
|
||||
- Deploying from private registries: serving/deploying-from-private-registry/README.md
|
||||
- Tag resolution: serving/tag-resolution.md
|
||||
- Gradually rolling out latest Revisions: serving/rolling-out-latest-revision.md
|
||||
|
|
@ -289,6 +293,9 @@ plugins:
|
|||
'upgrade/upgrade-installation-with-operator.md': 'admin/upgrade/upgrade-installation-with-operator.md'
|
||||
'upgrade/upgrade-installation.md': 'admin/upgrade/upgrade-installation.md'
|
||||
'install/check-install-version.md': 'check-install-version.md'
|
||||
'serving/services/private-services.md': 'developer/serving/services/private-services.md'
|
||||
'serving/services/creating-services.md': 'developer/serving/services/creating-services.md'
|
||||
'serving/services/README.md': 'developer/serving/services/README.md'
|
||||
|
||||
copyright: "Copyright © 2021 The Knative Authors"
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue