Updates to services docs

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.

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"
 ---
 

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.

docs/serving/services/creating-services.md

@@ -1,76 +1,71 @@
 ---
 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:
 
 * 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
+## 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.

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: