Skip to content

Commit

Permalink
添加2.1 changing things up 的内容翻译 (kubernetes-sigs#71)
Browse files Browse the repository at this point in the history
  • Loading branch information
@luffyao
luffyao committed Jul 26, 2020
1 parent 0d73c26 commit a67914e
Show file tree
Hide file tree
Showing 4 changed files with 92 additions and 115 deletions.
36 changes: 12 additions & 24 deletions docs/book/src/multiversion-tutorial/api-changes.md
View file
Original file line number Diff line number Diff line change
@@ -1,53 +1,41 @@
# Changing things up
# 修改

A fairly common change in a Kubernetes API is to take some data that used
to be unstructured or stored in some special string format, and change it
to structured data. Our `schedule` field fits the bill quite nicely for
this -- right now, in `v1`, our schedules look like
Kubernetes API 中一个相当常见的改变是获取一些非结构化的或者存储在一些特殊的字符串格式的数据，
并将其修改为结构化的数据。我们的 `schedule` 字段非常适合这个案例 -- 现在，在 `v1` 中，我们的 schedules 是这样的

```yaml
schedule: "*/1 * * * *"
```

That's a pretty textbook example of a special string format (it's also
pretty unreadable unless you're a Unix sysadmin).
这是一个非常典型的特殊字符串格式的例子（除非你是一个 Unix 系统管理员，否则非常难以理解它）。

Let's make it a bit more structured. According to the our [CronJob
code][cronjob-sched-code], we support "standard" Cron format.
让我们来使它更结构化一点。根据我们 [CronJob 代码][cronjob-sched-code]，我们支持"standard" Cron 格式。

In Kubernetes, **all versions must be safely round-tripable through each
other**. This means that if we convert from version 1 to version 2, and
then back to version 1, we must not lose information. Thus, any change we
make to our API must be compatible with whatever we supported in v1, and
also need to make sure anything we add in v2 is supported in v1. In some
cases, this means we need to add new fields to v1, but in our case, we
won't have to, since we're not adding new functionality.
在 Kubernetes 里，**所有版本都必须通过彼此进行安全的往返**。这意味着如果我们从版本 1 转换到版本 2，然后回退到版本 1，我们一定会失去一些信息。因此，我们对 API 所做的任何更改都必须与 v1 中所支持的内容兼容还需要确保我们添加到 v2 中的任何内容在 v1 中都得到支持。某些情况下，这意味着我们需要向 V1 中添加新的字段，但是在我们这个例子中，我们不会这么做，因为我们没有添加新的功能。

Keeping all that in mind, let's convert our example above to be
slightly more structured:
记住这些，让我们将上面的示例转换为稍微更结构化一点：

```yaml
schedule:
minute: */1
```

Now, at least, we've got labels for each of our fields, but we can still
easily support all the different syntax for each field.
现在，至少我们每个字段都有了标签，但是我们仍然可以为每个字段轻松地支持所有不同的语法。

We'll need a new API version for this change. Let's call it v2:
对这个改变我们将需要一个新的 API 版本。我们称它为 v2:

```shell
kubebuilder create api --group batch --version v2 --kind CronJob
```

Now, let's copy over our existing types, and make the change:
现在，让我们复制已经存在的类型，并做一些改变：

{{#literatego ./testdata/project/api/v2/cronjob_types.go}}

## Storage Versions
## 存储版本

{{#literatego ./testdata/project/api/v1/cronjob_types.go}}

Now that we've got our types in place, we'll need to set up conversion...
现在我们已经准备好了类型，接下来需要设置转换。

[cronjob-sched-code]: /TODO.md
74 changes: 35 additions & 39 deletions docs/book/src/multiversion-tutorial/testdata/project/api/v1/cronjob_types.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,108 +26,104 @@ import (
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
)

// EDIT THIS FILE! THIS IS SCAFFOLDING FOR YOU TO OWN!
// NOTE: json tags are required. Any new fields you add must have json tags for the fields to be serialized.
// 编辑这个文件！这是你拥有的脚手架！
// 注意: json 标签是必需的。为了字段能够被序列化任何你添加的新的字段一定有 json 标签。

// +kubebuilder:docs-gen:collapse=Imports

// CronJobSpec defines the desired state of CronJob
// CronJobSpec 定义了 CronJob 期待的状态
type CronJobSpec struct {
// +kubebuilder:validation:MinLength=0

// The schedule in Cron format, see https://en.wikipedia.org/wiki/Cron.
// Cron 格式的 schedule，详情请看https://en.wikipedia.org/wiki/Cron。
Schedule string `json:"schedule"`

// +kubebuilder:validation:Minimum=0

// Optional deadline in seconds for starting the job if it misses scheduled
// time for any reason. Missed jobs executions will be counted as failed ones.
// 对于开始 job 以秒为单位的可选的并如果由于任何原因错失了调度的时间截止日期。未执行的
// job 将被统计为失败的 job 。
// +optional
StartingDeadlineSeconds *int64 `json:"startingDeadlineSeconds,omitempty"`

// Specifies how to treat concurrent executions of a Job.
// Valid values are:
// - "Allow" (default): allows CronJobs to run concurrently;
// - "Forbid": forbids concurrent runs, skipping next run if previous run hasn't finished yet;
// - "Replace": cancels currently running job and replaces it with a new one
// 指定如何处理job的并发执行。
// 有效的值是：
// - "Allow" (默认)： 允许 CronJobs 并发执行；
// - "Forbid"：禁止并发执行，如果之前运行的还没有完成，跳过下一次执行；
// - "Replace"： 取消当前正在运行的 job 并用新的 job 替换它
// +optional
ConcurrencyPolicy ConcurrencyPolicy `json:"concurrencyPolicy,omitempty"`

// This flag tells the controller to suspend subsequent executions, it does
// not apply to already started executions. Defaults to false.
// 此标志告诉控制器暂停后续执行，它不会应用到已经开始执行的 job 。默认值是 false。
// +optional
Suspend *bool `json:"suspend,omitempty"`

// Specifies the job that will be created when executing a CronJob.
// 指定当执行一个 CronJob 时将会被创建的 job 。
JobTemplate batchv1beta1.JobTemplateSpec `json:"jobTemplate"`

// +kubebuilder:validation:Minimum=0

// The number of successful finished jobs to retain.
// This is a pointer to distinguish between explicit zero and not specified.
// 要保留的成功完成的 jobs 的数量。
// 这是一个用来区分明确 0 值和未指定的指针。
// +optional
SuccessfulJobsHistoryLimit *int32 `json:"successfulJobsHistoryLimit,omitempty"`

// +kubebuilder:validation:Minimum=0

// The number of failed finished jobs to retain.
// This is a pointer to distinguish between explicit zero and not specified.
// 要保留的失败的 jobs 的数量。
// 这是一个用来区分明确 0 值和未指定的指针。
// +optional
FailedJobsHistoryLimit *int32 `json:"failedJobsHistoryLimit,omitempty"`
}

// ConcurrencyPolicy describes how the job will be handled.
// Only one of the following concurrent policies may be specified.
// If none of the following policies is specified, the default one
// is AllowConcurrent.
// ConcurrencyPolicy 描述 job 将会被怎样处理。仅仅下面并发策略中的一种可以被指定。
// 如果没有指定下面策略的任何一种，那么默认的一个是 AllowConcurrent 。
// +kubebuilder:validation:Enum=Allow;Forbid;Replace
type ConcurrencyPolicy string

const (
// AllowConcurrent allows CronJobs to run concurrently.
// AllowConcurrent 允许 CronJobs 并发执行.
AllowConcurrent ConcurrencyPolicy = "Allow"

// ForbidConcurrent forbids concurrent runs, skipping next run if previous
// ForbidConcurrent 禁止并发执行, 如果之前运行的还没有完成，跳过下一次执行
// hasn't finished yet.
ForbidConcurrent ConcurrencyPolicy = "Forbid"

// ReplaceConcurrent cancels currently running job and replaces it with a new one.
// ReplaceConcurrent 取消当前正在运行的 job 并用新的 job 替换它。
ReplaceConcurrent ConcurrencyPolicy = "Replace"
)

// CronJobStatus defines the observed state of CronJob
// CronJobStatus 定义了 CronJob 观察的的状态
type CronJobStatus struct {
// INSERT ADDITIONAL STATUS FIELD - define observed state of cluster
// Important: Run "make" to regenerate code after modifying this file
// 插入额外的 STATUS 字段 - 定义集群观察的状态
// 重要：修改了这个文件之后运行"make"去重新生成代码

// A list of pointers to currently running jobs.
// 一个存储当前正在运行 job 的指针列表。
// +optional
Active []corev1.ObjectReference `json:"active,omitempty"`

// Information when was the last time the job was successfully scheduled.
// 当 job 最后一次成功被调度的信息。
// +optional
LastScheduleTime *metav1.Time `json:"lastScheduleTime,omitempty"`
}

// +kubebuilder:docs-gen:collapse=old stuff

/*
Since we'll have more than one version, we'll need to mark a storage version.
This is the version that the Kubernetes API server uses to store our data.
We'll chose the v1 version for our project.
因为我们将有多个版本，我们将需要标记一个存储版本。
这是一个 Kubernetes API 服务端使用存储我们数据的版本。
我们将选择v1版本作为我们项目的版本。
We'll use the [`+kubebuilder:storageversion`](/reference/markers/crd.md) to do this.
我们将用 [`+kubebuilder:storageversion`](/reference/markers/crd.md) 去做这件事。
Note that multiple versions may exist in storage if they were written before
the storage version changes -- changing the storage version only affects how
objects are created/updated after the change.
注意如果在存储版本改变之前它们已经被写入那么在仓库中可能存在多个版本 -- 改变存储版本仅仅影响
在改变之后对象的创建/更新。
*/

// +kubebuilder:object:root=true
// +kubebuilder:subresource:status
// +kubebuilder:storageversion

// CronJob is the Schema for the cronjobs API
// CronJob 是 cronjobs API 的 Schema
type CronJob struct {
metav1.TypeMeta `json:",inline"`
metav1.ObjectMeta `json:"metadata,omitempty"`
Expand All @@ -141,7 +137,7 @@ type CronJob struct {

// +kubebuilder:object:root=true

// CronJobList contains a list of CronJob
// CronJobList 包含了一个 CronJob 的列表
type CronJobList struct {
metav1.TypeMeta `json:",inline"`
metav1.ListMeta `json:"metadata,omitempty"`
Expand Down
Loading

0 comments on commit a67914e

Please sign in to comment.