Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: keep writing consistent across pages #1000

Merged
merged 1 commit into from
Mar 19, 2024
+102 −53
Merged

docs: keep writing consistent across pages #1000

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 27 additions & 14 deletions site/content/en/docs/user/attach-configuration.md
View file
Open in desktop
Original file line number Diff line number Diff line change
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
Open in desktop
Original file line number Diff line number Diff line change
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
Open in desktop
Original file line number Diff line number Diff line change
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
Open in desktop
Original file line number Diff line number Diff line change
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
Loading