Skip to content
Permalink
Browse files

Consolidate YAML files [part-13] (#9377)

This PR deals with YAML files referenced by the following two topics:
- concepts:object management
- concepts:service networking

When scanning references to the YAML files to be moved, some trivial
editings were applied to the markdown files. None of this editing should
break the build or ruin the doc otherwise.
  • Loading branch information...
tengqm authored and k8s-ci-robot committed Jul 10, 2018
1 parent f9901e7 commit 99a77ff368125039e3a7a74cc3fde228efd065c9
Showing with 160 additions and 134 deletions.
  1. +18 −49 content/en/docs/concepts/overview/object-management-kubectl/declarative-config.md
  2. +5 −3 content/en/docs/concepts/overview/working-with-objects/kubernetes-objects.md
  3. +0 −19 content/en/docs/concepts/overview/working-with-objects/nginx-deployment.yaml
  4. +16 −17 content/en/docs/concepts/services-networking/add-entries-to-pod-etc-hosts-with-host-aliases.md
  5. +54 −16 content/en/docs/concepts/services-networking/connect-applications-service.md
  6. +1 −1 content/en/docs/concepts/services-networking/dns-pod-service.md
  7. +55 −13 content/en/docs/concepts/services-networking/ingress.md
  8. 0 .../{docs/concepts/overview/object-management-kubectl → examples/application}/simple_deployment.yaml
  9. 0 .../{docs/concepts/overview/object-management-kubectl → examples/application}/update_deployment.yaml
  10. 0 content/en/{docs/concepts/services-networking → examples/service/networking}/curlpod.yaml
  11. 0 content/en/{docs/concepts/services-networking → examples/service/networking}/custom-dns.yaml
  12. 0 content/en/{docs/concepts/services-networking → examples/service/networking}/hostaliases-pod.yaml
  13. 0 content/en/{docs/concepts/services-networking → examples/service/networking}/ingress.yaml
  14. 0 content/en/{docs/concepts/services-networking → examples/service/networking}/nginx-secure-app.yaml
  15. 0 content/en/{docs/concepts/services-networking → examples/service/networking}/nginx-svc.yaml
  16. 0 content/en/{docs/concepts/services-networking → examples/service/networking}/run-my-nginx.yaml
  17. +11 −16 test/examples_test.go
@@ -65,18 +65,18 @@ configuration file that was used to create the object.

Here's an example of an object configuration file:

{{< code file="simple_deployment.yaml" >}}
{{< codenew file="application/simple_deployment.yaml" >}}

Create the object using `kubectl apply`:

```shell
kubectl apply -f https://k8s.io/docs/concepts/overview/object-management-kubectl/simple_deployment.yaml
kubectl apply -f https://k8s.io/examples/application/simple_deployment.yaml
```

Print the live configuration using `kubectl get`:

```shell
kubectl get -f https://k8s.io/docs/concepts/overview/object-management-kubectl/simple_deployment.yaml -o yaml
kubectl get -f https://k8s.io/examples/application/simple_deployment.yaml -o yaml
```

The output shows that the `kubectl.kubernetes.io/last-applied-configuration` annotation
@@ -139,12 +139,12 @@ kubectl apply -f <directory>/

Here's an example configuration file:

{{< code file="simple_deployment.yaml" >}}
{{< codenew file="application/simple_deployment.yaml" >}}

Create the object using `kubectl apply`:

```shell
kubectl apply -f https://k8s.io/docs/concepts/overview/object-management-kubectl/simple_deployment.yaml
kubectl apply -f https://k8s.io/examples/application/simple_deployment.yaml
```

{{< note >}}
@@ -155,7 +155,7 @@ configuration file instead of a directory.
Print the live configuration using `kubectl get`:

```shell
kubectl get -f https://k8s.io/docs/concepts/overview/object-management-kubectl/simple_deployment.yaml -o yaml
kubectl get -f https://k8s.io/examples/application/simple_deployment.yaml -o yaml
```

The output shows that the `kubectl.kubernetes.io/last-applied-configuration` annotation
@@ -210,7 +210,7 @@ kubectl scale deployment/nginx-deployment --replicas=2
Print the live configuration using `kubectl get`:

```shell
kubectl get -f https://k8s.io/docs/concepts/overview/object-management-kubectl/simple_deployment.yaml -o yaml
kubectl get -f https://k8s.io/examples/application/simple_deployment.yaml -o yaml
```

The output shows that the `replicas` field has been set to 2, and the `last-applied-configuration`
@@ -257,18 +257,18 @@ spec:
Update the `simple_deployment.yaml` configuration file to change the image from
`nginx:1.7.9` to `nginx:1.11.9`, and delete the `minReadySeconds` field:

{{< code file="update_deployment.yaml" >}}
{{< codenew file="application/update_deployment.yaml" >}}

Apply the changes made to the configuration file:

```shell
kubectl apply -f https://k8s.io/docs/concepts/overview/object-management-kubectl/update_deployment.yaml
kubectl apply -f https://k8s.io/examples/application/update_deployment.yaml
```

Print the live configuration using `kubectl get`:

```
kubectl get -f https://k8s.io/docs/concepts/overview/object-management-kubectl/simple_deployment.yaml -o yaml
kubectl get -f https://k8s.io/examples/application/simple_deployment.yaml -o yaml
```

The output shows the following changes to the live configuration:
@@ -417,7 +417,7 @@ to calculate which fields should be deleted or set:

Here's an example. Suppose this is the configuration file for a Deployment object:

{{< code file="update_deployment.yaml" >}}
{{< codenew file="application/update_deployment.yaml" >}}

Also, suppose this is the live configuration for the same Deployment object:

@@ -463,7 +463,10 @@ Here are the merge calculations that would be performed by `kubectl apply`:

1. Calculate the fields to delete by reading values from
`last-applied-configuration` and comparing them to values in the
configuration file. In this example, `minReadySeconds` appears in the
configuration file.
Clear fields explicitly set to null in the local object configuration file
regardless of whether they appear in the `last-applied-configuration`.
In this example, `minReadySeconds` appears in the
`last-applied-configuration` annotation, but does not appear in the configuration file.
**Action:** Clear `minReadySeconds` from the live configuration.
2. Calculate the fields to set by reading values from the configuration
@@ -517,12 +520,6 @@ spec:
# ...
```

{{< comment >}}
TODO(1.6): For 1.6, add the following bullet point to 1.

- clear fields explicitly set to null in the local object configuration file regardless of whether they appear in the last-applied-configuration
{{< /comment >}}

### How different types of fields are merged

How a particular field in a configuration file is merged with
@@ -716,18 +713,18 @@ not specified when the object is created.

Here's a configuration file for a Deployment. The file does not specify `strategy`:

{{< code file="simple_deployment.yaml" >}}
{{< codenew file="application/simple_deployment.yaml" >}}

Create the object using `kubectl apply`:

```shell
kubectl apply -f https://k8s.io/docs/concepts/overview/object-management-kubectl/simple_deployment.yaml
kubectl apply -f https://k8s.io/examples/application/simple_deployment.yaml
```

Print the live configuration using `kubectl get`:

```shell
kubectl get -f https://k8s.io/docs/concepts/overview/object-management-kubectl/simple_deployment.yaml -o yaml
kubectl get -f https://k8s.io/examples/application/simple_deployment.yaml -o yaml
```

The output shows that the API server set several fields to default values in the live
@@ -871,31 +868,10 @@ Recommendation: These fields should be explicitly defined in the object configur

### How to clear server-defaulted fields or fields set by other writers

As of Kubernetes 1.5, fields that do not appear in the configuration file cannot be
cleared by a merge operation. Here are some workarounds:

Option 1: Remove the field by directly modifying the live object.

{{< note >}}
**Note:** As of Kubernetes 1.5, `kubectl edit` does not work with `kubectl apply`.
Using these together will cause unexpected behavior.
{{< /note >}}

Option 2: Remove the field through the configuration file.

1. Add the field to the configuration file to match the live object.
1. Apply the configuration file; this updates the annotation to include the field.
1. Delete the field from the configuration file.
1. Apply the configuration file; this deletes the field from the live object and annotation.

{{< comment >}}
TODO(1.6): Update this with the following for 1.6

Fields that do not appear in the configuration file can be cleared by
setting their values to `null` and then applying the configuration file.
For fields defaulted by the server, this triggers re-defaulting
the values.
{{< /comment >}}

## How to change ownership of a field between the configuration file and direct imperative writers

@@ -994,13 +970,6 @@ template:
controller-selector: "extensions/v1beta1/deployment/nginx"
```

## Known Issues

* Prior to Kubernetes 1.6, `kubectl apply` did not support operating on objects stored in a
[custom resource](/docs/concepts/api-extension/custom-resources/).
For these cluster versions, you should instead use [imperative object configuration](/docs/concepts/overview/object-management-kubectl/imperative-config/).
{{% /capture %}}

{{% capture whatsnext %}}
- [Managing Kubernetes Objects Using Imperative Commands](/docs/concepts/overview/object-management-kubectl/imperative-command/)
- [Imperative Management of Kubernetes Objects Using Configuration Files](/docs/concepts/overview/object-management-kubectl/imperative-config/)
@@ -36,12 +36,14 @@ When you create an object in Kubernetes, you must provide the object spec that d

Here's an example `.yaml` file that shows the required fields and object spec for a Kubernetes Deployment:

{{< code file="nginx-deployment.yaml" >}}
{{< codenew file="application/deployment.yaml" >}}

One way to create a Deployment using a `.yaml` file like the one above is to use the [`kubectl create`](/docs/reference/generated/kubectl/kubectl-commands#create) command in the `kubectl` command-line interface, passing the `.yaml` file as an argument. Here's an example:
One way to create a Deployment using a `.yaml` file like the one above is to use the
[`kubectl create`](/docs/reference/generated/kubectl/kubectl-commands#create) command
in the `kubectl` command-line interface, passing the `.yaml` file as an argument. Here's an example:

```shell
$ kubectl create -f https://k8s.io/docs/concepts/overview/working-with-objects/nginx-deployment.yaml --record
$ kubectl create -f https://k8s.io/examples/application/deployment.yaml --record
```

The output is similar to this:

This file was deleted.

Oops, something went wrong.
@@ -44,13 +44,17 @@ fe00::2 ip6-allrouters
10.200.0.4 nginx
```

by default, the hosts file only includes ipv4 and ipv6 boilerplates like `localhost` and its own hostname.
By default, the `hosts` file only includes IPv4 and IPv6 boilerplates like
`localhost` and its own hostname.

## Adding Additional Entries with HostAliases

In addition to the default boilerplate, we can add additional entries to the hosts file to resolve `foo.local`, `bar.local` to `127.0.0.1` and `foo.remote`, `bar.remote` to `10.1.2.3`, we can by adding HostAliases to the Pod under `.spec.hostAliases`:
In addition to the default boilerplate, we can add additional entries to the
`hosts` file to resolve `foo.local`, `bar.local` to `127.0.0.1` and `foo.remote`,
`bar.remote` to `10.1.2.3`, we can by adding HostAliases to the Pod under
`.spec.hostAliases`:

{{< code file="hostaliases-pod.yaml" >}}
{{< codenew file="service/networking/hostaliases-pod.yaml" >}}

This Pod can be started with the following commands:

@@ -63,7 +67,7 @@ NAME READY STATUS RESTARTS AGE IP
hostaliases-pod 0/1 Completed 0 6s 10.244.135.10 node3
```

The hosts file content would look like this:
The `hosts` file content would look like this:

```shell
$ kubectl logs hostaliases-pod
@@ -83,22 +87,17 @@ fe00::2 ip6-allrouters

With the additional entries specified at the bottom.

## Limitations

HostAlias is only supported in 1.7+.

HostAlias support in 1.7 is limited to non-hostNetwork Pods because kubelet only manages the hosts file for non-hostNetwork Pods.

In 1.8, HostAlias is supported for all Pods regardless of network configuration.

## Why Does Kubelet Manage the Hosts File?

Kubelet [manages](https://github.com/kubernetes/kubernetes/issues/14633) the hosts file for each container of the Pod to prevent Docker from [modifying](https://github.com/moby/moby/issues/17190) the file after the containers have already been started.
Kubelet [manages](https://github.com/kubernetes/kubernetes/issues/14633) the
`hosts` file for each container of the Pod to prevent Docker from
[modifying](https://github.com/moby/moby/issues/17190) the file after the
containers have already been started.

Because of the managed-nature of the file, any user-written content will be overwritten whenever the hosts file is remounted by Kubelet in the event of a container restart or a Pod reschedule. Thus, it is not suggested to modify the contents of the file.
Because of the managed-nature of the file, any user-written content will be
overwritten whenever the `hosts` file is remounted by Kubelet in the event of
a container restart or a Pod reschedule. Thus, it is not suggested to modify
the contents of the file.

{{% /capture %}}

{{% capture whatsnext %}}

{{% /capture %}}
Oops, something went wrong.

0 comments on commit 99a77ff

Please sign in to comment.
You can’t perform that action at this time.