Skip to content

Commit

Permalink
docs: keep writing consistent across pages
Browse files Browse the repository at this point in the history
  • Loading branch information
@caozhuozi
caozhuozi committed Mar 17, 2024
1 parent 7c7daed commit 66cc216
Show file tree
Hide file tree
Showing 4 changed files with 102 additions and 53 deletions.
41 changes: 27 additions & 14 deletions site/content/en/docs/user/attach-configuration.md
View file
Expand Up @@ -10,11 +10,11 @@ This document walks you through how to configure the Attach feature.

{{< /hint >}}

## What is a Attach?
## What is an Attach?

The [Attach API] is a [`kwok` Configuration][configuration] that allows users to define and simulate attaching to Pod(s).
The [Attach] is a [`kwok` Configuration][configuration] that allows users to define and simulate attaching to a single pod.

A Attach resource has the following fields:
The YAML below shows all the fields of an Attach resource:

``` yaml
kind: Attach
Expand All @@ -29,17 +29,24 @@ spec:
logsFile: <string>
```

To attach a container, you can set the `attaches` field in the spec section of an Attach resource.
The `containers` field is used to match an item in the `attaches` field, and the `logsFile` field specifies the file path of the logs.
Only attach to the containers specified in the `containers` field will be attached to the `logsFile`.
If the `containers` field is not set, the `attaches` item will default to all containers.
To associate an Attach with a certain pod to be simulated, users must ensure `metadata.name` and `metadata.namespace`
are inconsistent with the name and namespace of the target pod.

The attaching simulation setting of a pod are specified via `attaches` field.
The `attaches` field is organized by groups, with each corresponding to a collection of containers that shares a same attaching simulation setting.
Each group consists of a list of container names (`containers`) and the shared attaching simulation setting (`logsFile`).

{{< hint "info" >}}
If `containers` is not given in a group, the `logsFile` in that group will be applied to all containers of the target pod.
{{< /hint >}}

The `logsFile` field specifies the file path of the logs. If the `logsFile` field is not set, this item will be ignored.

### ClusterAttach

The [ClusterAttach API] is a special Attach API which is cluster-side.
In addition to simulating a single pod, users can also simulate the attaching for multiple pods via [ClusterAttach].

A ClusterAttach resource has the following fields:
The YAML below shows all the fields of a ClusterAttach resource:

``` yaml
kind: ClusterAttach
Expand All @@ -58,14 +65,20 @@ spec:
logsFile: <string>
```

The `selector` field specifies the Pods to be attached.
The `matchNamespaces` field specifies the namespaces to be matched. If the `matchNamespaces` field is not set, the `matchNamespaces` field will default to all namespaces.
The `matchNames` field specifies the names to be matched. If the `matchNames` field is not set, the `matchNames` field will default to all names.
Compared to Attach, whose `metadata.name` and `metadata.namespace` are required to match the associated pod,
ClusterAttach has an additional `selector` field for specifying the target pods to be simulated.
`matchNamespaces` and `matchNames` are both represented as list，which are designed to take pod collections by different levels:

1. If `matchNamespaces` is empty, ClusterAttach will be applied to all pods that are managed by `kwok` and whose names listed in `matchNames`.
2. If `matchNames` is empty, ClusterAttach will be applied to all pods managed by `kwok` and under namespaces listed in `matchNamespaces`.
3. If `matchNames` and `matchNamespaces` are both unset, ClusterAttach will be applied to all pods that `kwok` manages.

The `attaches` field of ClusterAttach has the same semantic with the one in Attach.

## Examples

<img width="700px" src="/img/demo/attach.svg">

[configuration]: {{< relref "/docs/user/configuration" >}}
[Attach API]: {{< relref "/docs/generated/apis" >}}#kwok.x-k8s.io/v1alpha1.Attach
[ClusterAttach API]: {{< relref "/docs/generated/apis" >}}#kwok.x-k8s.io/v1alpha1.ClusterAttach
[Attach]: {{< relref "/docs/generated/apis" >}}#kwok.x-k8s.io/v1alpha1.Attach
[ClusterAttach]: {{< relref "/docs/generated/apis" >}}#kwok.x-k8s.io/v1alpha1.ClusterAttach
41 changes: 28 additions & 13 deletions site/content/en/docs/user/exec-configuration.md
View file
Expand Up @@ -10,11 +10,11 @@ This document walks you through how to configure the Exec feature.

{{< /hint >}}

## What is a Exec?
## What is an Exec?

The [Exec API] is a [`kwok` Configuration][configuration] that allows users to define and simulate exec to Pod(s).
The [Exec] is a [`kwok` Configuration][configuration] that allows users to define and simulate exec to a single pod.

A Exec resource has the following fields:
The YAML below shows all the fields of an Exec resource:

``` yaml
kind: Exec
Expand All @@ -33,17 +33,26 @@ spec:
value: <string>
```

To exec a container, you can set the `execs` field in the spec section of a Exec resource.
The `containers` field is used to match an item in the `execs` field. If the `containers` field is not set, the `execs` item will default to all containers.
To associate an Exec with a certain pod to be simulated, users must ensure `metadata.name` and `metadata.namespace`
are inconsistent with the name and namespace of the target pod.

The exec simulation setting of a pod are specified via `execs` field.
The `execs` field is organized by groups, with each corresponding to a collection of containers that shares a same exec simulation setting.
Each group consists of a list of container names (`containers`) and the shared exec simulation setting (`local`).

{{< hint "info" >}}
If `containers` is not given in a group, the `usage` in that group will be applied to all containers of the target pod.
{{< /hint >}}

The `local` field specifies the local environment to be executed.
The `workDir` field specifies the working directory of the local environment. If the `workDir` field is not set, the working directory will be the root directory.
The `workDir` field specifies the working directory of the local environment. If not set, the working directory will be the root directory.
The `envs` field specifies the environment variables of the local environment.

### ClusterExec

The [ClusterExec API] is a special Exec API which is cluster-side.
In addition to simulating a single pod, users can also simulate the resource usage for multiple pods via [ClusterExec].

A ClusterExec resource has the following fields:
The YAML below shows all the fields of a ClusterExec resource:

``` yaml
kind: ClusterExec
Expand All @@ -66,14 +75,20 @@ spec:
value: <string>
```

The `selector` field specifies the Pods to be executed.
The `matchNamespaces` field specifies the namespaces to be matched. If the `matchNamespaces` field is not set, the `ClusterExec` will match all namespaces.
The `matchNames` field specifies the names to be matched. If the `matchNames` field is not set, the `ClusterExec` will match all names.
Compared to Exec, whose `metadata.name` and `metadata.namespace` are required to match the associated pod,
ClusterExec has an additional `selector` field for specifying the target pods to be simulated.
`matchNamespaces` and `matchNames` are both represented as list，which are designed to take pod collections by different levels:

1. If `matchNamespaces` is empty, ClusterExec will be applied to all pods that are managed by `kwok` and whose names listed in `matchNames`.
2. If `matchNames` is empty, ClusterExec will be applied to all pods managed by `kwok` and under namespaces listed in `matchNamespaces`.
3. If `matchNames` and `matchNamespaces` are both unset, ClusterExec will be applied to all pods that `kwok` manages.

The `execs` field of ClusterExec has the same semantic with the one in Exec.

## Examples

<img width="700px" src="/img/demo/exec.svg">

[configuration]: {{< relref "/docs/user/configuration" >}}
[Exec API]: {{< relref "/docs/generated/apis" >}}#kwok.x-k8s.io/v1alpha1.Exec
[ClusterExec API]: {{< relref "/docs/generated/apis" >}}#kwok.x-k8s.io/v1alpha1.ClusterExec
[Exec]: {{< relref "/docs/generated/apis" >}}#kwok.x-k8s.io/v1alpha1.Exec
[ClusterExec]: {{< relref "/docs/generated/apis" >}}#kwok.x-k8s.io/v1alpha1.ClusterExec
33 changes: 22 additions & 11 deletions site/content/en/docs/user/logs-configuration.md
View file
Expand Up @@ -12,9 +12,9 @@ This document walks you through how to configure the Logs feature.

## What is a Logs?

The [Logs API] is a [`kwok` Configuration][configuration] that allows users to define and simulate logs to Pod(s).
The [Logs] is a [`kwok` Configuration][configuration] that allows users to define and simulate logs to a single pod.

A Logs resource has the following fields:
The YAML below shows all the fields of a Logs resource:

``` yaml
kind: Logs
Expand All @@ -29,17 +29,22 @@ spec:
logsFile: <string>
follow: <bool>
```
The logs simulation setting of a pod is specified via `logs` field.
The `logs` field is organized by groups, with each corresponding to a collection of containers that shares a same logs simulation config.
Each group consists of a list of container names (`containers`) and the shared simulation settings (`logsFile` and `follow`).

{{< hint "info" >}}
If `containers` is not given in a group, the `logsFile` and `follow` in that group will be applied to all containers of the target pod.
{{< /hint >}}

To log a container, you can set the `logs` field in the spec section of a Logs resource.
The `containers` field is used to match an item in the `logs` field. If the `containers` field is not set, the `logs` item will default to all containers.
The `logsFile` field specifies the file path of the logs. If the `logsFile` field is not set, this item will be ignored.
The `follow` field specifies whether to follow the logs. If the `follow` field is not set, the `follow` field will default to false.

### ClusterLogs

The [ClusterLogs API] is a special Logs API which is cluster-side.
In addition to simulating a single pod, users can also simulate the logs for multiple pods via [ClusterLogs].

A ClusterLogs resource has the following fields:
The YAML below shows all the fields of a ClusterLogs resource:

``` yaml
kind: ClusterLogs
Expand All @@ -59,14 +64,20 @@ spec:
follow: <bool>
```

The `selector` field specifies the Pods to be logged.
The `matchNamespaces` field specifies the namespaces to be matched. If the `matchNamespaces` field is not set, the `matchNamespaces` field will default to all namespaces.
The `matchNames` field specifies the names to be matched. If the `matchNames` field is not set, the `matchNames` field will default to all names.
Compared to Logs, whose `metadata.name` and `metadata.namespace` are required to match the associated pod,
ClusterLogs has an additional `selector` field for specifying the target pods to be simulated.
`matchNamespaces` and `matchNames` are both represented as list，which are designed to take pod collections by different levels:

1. If `matchNamespaces` is empty, ClusterLogs will be applied to all pods that are managed by `kwok` and whose names listed in `matchNames`.
2. If `matchNames` is empty, ClusterLogs will be applied to all pods managed by `kwok` and under namespaces listed in `matchNamespaces`.
3. If `matchNames` and `matchNamespaces` are both unset, ClusterLogs will be applied to all pods that `kwok` manages.

The `logs` field of ClusterLogs has the same semantic with the one in Logs.

## Examples

<img width="700px" src="/img/demo/logs.svg">

[configuration]: {{< relref "/docs/user/configuration" >}}
[Logs API]: {{< relref "/docs/generated/apis" >}}#kwok.x-k8s.io/v1alpha1.Logs
[ClusterLogs API]: {{< relref "/docs/generated/apis" >}}#kwok.x-k8s.io/v1alpha1.ClusterLogs
[Logs]: {{< relref "/docs/generated/apis" >}}#kwok.x-k8s.io/v1alpha1.Logs
[ClusterLogs]: {{< relref "/docs/generated/apis" >}}#kwok.x-k8s.io/v1alpha1.ClusterLogs
40 changes: 25 additions & 15 deletions site/content/en/docs/user/port-forward-configuration.md
View file
Expand Up @@ -12,9 +12,9 @@ This document walks you through how to configure the PortForward feature.

## What is a PortForward?

The [PortForward API] is a [`kwok` Configuration][configuration] that allows users to define and simulate port forwarding to Pod(s).
The [PortForward] is a [`kwok` Configuration][configuration] that allows users to define and simulate port forwarding to a single pod.

A PortForward resource has the following fields:
The YAML below shows all the fields of a PortForward resource:

``` yaml
kind: PortForward
Expand All @@ -29,24 +29,30 @@ spec:
target:
port: <int>
address: <string>
- ports:
- <int>
command:
- <string>
- <string>
```
To associate a PortForward with a certain pod to be simulated, users must ensure `metadata.name` and `metadata.namespace`
are inconsistent with the name and namespace of the target pod.

The attaching setting of a pod are specified via `forwards` field.
The `forwards` field is organized by groups, with each corresponding to a collection of ports that shares a same forwarding setting.
Each group consists of a list of ports numbers (`ports`) and the shared forwarding setting (`target` and `command`).

{{< hint "info" >}}
If `ports` is not given in a group, the `target` and `command` in that group will be applied to all ports of the target pod.
{{< /hint >}}

To forward a port, you can set the `forwards` field in the spec section of a PortForward resource.
The `ports` field is used to match an item in the `forwards` field. If the `ports` field is not set, the `forwards` item will default to all ports.
The `target` field specifies the target address to be forwarded to. If the `command` field is set, the `target` field will be ignored.
The `command` field allows users to define the command to be executed to forward the port. The `command` is executed in the container of kwok.
The `command` should be a string array, where the first element is the command and the rest are the arguments. Also, the command should be in the container’s PATH.

### ClusterPortForward

The [ClusterPortForward API] is a special PortForward API which is cluster-side.
In addition to simulating a single pod, users can also simulate the port forwarding for multiple pods via [ClusterPortForward].

A ClusterPortForward resource has the following fields:
The YAML below shows all the fields of a ClusterPortForward resource:

``` yaml
kind: ClusterPortForward
Expand All @@ -65,21 +71,25 @@ spec:
target:
port: <int>
address: <string>
- ports:
- <int>
command:
- <string>
- <string>
```

The `selector` field is used to select the Pods to be port forwarded.
The `matchNamespaces` field is used to match the namespace of the Pods. If the `matchNamespaces` field is not set, the ClusterPortForward will match all namespaces.
The `matchNames` field is used to match the name of the Pods. If the `matchNames` field is not set, the ClusterPortForward will match all Pods.
Compared to PortForward, whose `metadata.name` and `metadata.namespace` are required to match the associated pod,
ClusterPortForward has an additional `selector` field for specifying the target pods to be simulated.
`matchNamespaces` and `matchNames` are both represented as list，which are designed to take pod collections by different levels:

1. If `matchNamespaces` is empty, ClusterPortForward will be applied to all pods that are managed by `kwok` and whose names listed in `matchNames`.
2. If `matchNames` is empty, ClusterPortForward will be applied to all pods managed by `kwok` and under namespaces listed in `matchNamespaces`.
3. If `matchNames` and `matchNamespaces` are both unset, ClusterPortForward will be applied to all pods that `kwok` manages.

The `forwards` field of ClusterPortForward has the same semantic with the one in PortForward.

## Examples

<img width="700px" src="/img/demo/port-forward.svg">

[configuration]: {{< relref "/docs/user/configuration" >}}
[PortForward API]: {{< relref "/docs/generated/apis" >}}#kwok.x-k8s.io/v1alpha1.PortForward
[ClusterPortForward API]: {{< relref "/docs/generated/apis" >}}#kwok.x-k8s.io/v1alpha1.ClusterPortForward
[PortForward]: {{< relref "/docs/generated/apis" >}}#kwok.x-k8s.io/v1alpha1.PortForward
[ClusterPortForward]: {{< relref "/docs/generated/apis" >}}#kwok.x-k8s.io/v1alpha1.ClusterPortForward

0 comments on commit 66cc216

Please sign in to comment.