Skip to content

Commit

Permalink
add en docs (labring#3475)
Browse files Browse the repository at this point in the history 
* docs(v5.0): gpt4.0 to en

Signed-off-by: cuisongliu <[email protected]>

* docs(v5.0): gpt3.5 to en

Signed-off-by: cuisongliu <[email protected]>

* docs(v5.0): gpt3.5 to en

Signed-off-by: cuisongliu <[email protected]>

* docs(v5.0): gpt4.0 to en

Signed-off-by: cuisongliu <[email protected]>

* docs(v5.0): gpt4.0 to en

Signed-off-by: cuisongliu <[email protected]>

---------

Signed-off-by: cuisongliu <[email protected]>
  • Loading branch information
@cuisongliu
cuisongliu committed Jul 7, 2023
1 parent 613ce0f commit 8110c77
Show file tree
Hide file tree
Showing 72 changed files with 1,569 additions and 1,675 deletions.
153 changes: 57 additions & 96 deletions docs/4.0/docs/lifecycle-management/QA.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,33 +2,33 @@
sidebar_position: 1
---

# 常见问题
# Frequently Asked Questions

使用Sealos时，您可能会遇到一些问题。以下是一些常见问题的答案和解决方法。
When using Sealos, you may encounter some common questions and issues. Here are answers and solutions to some of the common problems.

## 镜像构建问题
## Image Building Issues

### Q1: 在构建阶段如何设置代理服务？
### Q1: How to set up a proxy service during the build phase?

在执行构建命令时，可以通过设置HTTP_PROXY环境变量来配置代理服务。
During the execution of the build command, you can configure a proxy service by setting the HTTP_PROXY environment variable.

```shell
HTTP_PROXY=socket5://127.0.0.1:7890 sealos build xxxxx
```

### Q2：如何启用buildah的调试日志？
### Q2: How to enable debug logs for buildah?

若需要查看buildah的调试日志，可以通过设定`BUILDAH_LOG_LEVEL`环境变量实现。
To view debug logs for buildah, you can set the `BUILDAH_LOG_LEVEL` environment variable.

```shell
BUILDAH_LOG_LEVEL=debug sealos images
```

### Q3：如何在Pod中执行Sealos构建？
### Q3: How to execute Sealos build within a Pod?

若在Pod中执行Sealos构建，请按以下步骤操作：
If you want to execute Sealos build within a Pod, follow these steps:

1. 在Pod中构建镜像，可用以下YAML配置创建Deployment。
1. Build the image within the Pod. You can create a Deployment with the following YAML configuration:

```yaml
apiVersion: apps/v1
Expand All @@ -49,15 +49,15 @@ spec:
app: sealoscli
spec:
containers:
- image: #用你的sealos镜像替换
- image: # Replace with your sealos image
name: sealoscli
stdin: true
stdinOnce: true
securityContext:
privileged: true
```
2. 创建Dockerfile。以下是一个例子，根据需要进行修改。
2. Create a Dockerfile. Here's an example that you can modify as per your needs:
```dockerfile
FROM bitnami/minideb:buster
Expand All @@ -76,128 +76,89 @@ ENV LC_ALL=C.UTF-8
ENV TZ=Asia/Shanghai
```

3. 在Pod中执行构建命令。
3. Execute the build command within the Pod.

```shell
sealos build --arch arm64 --build-arg TARGETOS=linux --build-arg TARGETARCH=arm64 -t test -f Dockerfile .
```

### Q4：执行Sealos构建时遇到“lgetxattr /var/lib/containers/storage/overlay/0c2afe770ec7870ad4639f18a1b50b3a84718f95c8907f3d54e14dbf0a01d50d/merged/dev/ptmx: no such device”错误？
### Q4: Encounter the error "lgetxattr /var/lib/containers/storage/overlay/0c2afe770ec7870ad4639f18a1b50b3a84718f95c8907f3d54e14dbf0a01d50d/merged/dev/ptmx: no such device" during Sealos build. How to fix it?

这个问题可能与`fuse-overlayfs`的版本有关。建议您从[这里](https://github.com/containers/fuse-overlayfs/releases)下载最新版本下载并替换`/bin/fuse-overlayfs`。
This issue might be related to the version of `fuse-overlayfs`. We recommend downloading the latest version from [here](https://github.com/containers/fuse-overlayfs/releases) and replacing `/bin/fuse-overlayfs`.

## 运行时选择问题
## Runtime Selection Issues

### Q1：如何选择Kubernetes运行时？
### Q1: How to select the Kubernetes runtime?

Sealos会根据您选择的镜像决定使用哪种运行时。如果选择了kubernetes-docker镜像，Sealos将使用Docker作为运行时；如果选择了kubernetes-crio镜像，Sealos将使用CRI-O作为运行时。
Sealos determines the runtime based on the image you choose. If you select the `kubernetes-docker` image, Sealos will use Docker as the runtime. If you choose the `kubernetes-crio` image, Sealos will use CRI-O as the runtime.

## 版本兼容性问题
## Version Compatibility Issues

### Q1：报错："Applied to cluster error: failed to init exec auth.sh failed exit status 127"？
### Q1: Error "Applied to cluster error: failed to

此问题常因您使用的sealos版本和镜像版本不匹配造成。请确认您的镜像版本和sealos的版本是匹配的。
例如，若您正使用形如kubernetes:v1.xx.x的版本，可能需要升级sealos，特别是在使用较老版本的sealos，而sealos集群镜像则使用了最新版时。
另一种解决方法是选择对应版本的sealos镜像。比如，如果您的sealos版本是4.1.3，那么集群镜像应选择形如kuberntes:v1.24.0-4.1.3的版本。
确保镜像版本和sealos版本的匹配，可以帮助避免此类问题。
init exec auth.sh failed exit status 127"?

### Q2: 如果您在集群中新增了其他域名，或者修改了 service 的 CIDR，并且在添加 master 时出现了错误
This error is often caused by a mismatch between the version of Sealos and the version of the image being used. Make sure that the image version and the Sealos version are compatible. For example, if you are using a Kubernetes version like `v1.xx.x`, you may need to upgrade Sealos, especially if you are using an older version of Sealos while the Sealos cluster image is using the latest version. Another solution is to choose the corresponding version of the Sealos image. For example, if your Sealos version is 4.1.3, then the cluster image should be something like `kubernetes:v1.24.0-4.1.3`. Ensuring that the image version and Sealos version are compatible can help avoid such issues.

为了解决这个问题，Sealos 团队在 4.2.0 版本进行了相应的修复。具体的修复内容和讨论可以在这个 pull request 中查看：https://github.com/labring/sealos/pull/2943 。
### Q2: Error when adding additional domains or modifying the service CIDR in the cluster during the addition of a master node

所以，如果您遇到了这个问题，我们建议您升级到 Sealos 4.2.0 版本。更新后的版本应该能够正确处理这些变更，并且在添加 master 时不会出现错误。
To address this issue, the Sealos team made the necessary fixes in version 4.2.0. You can refer to the specific fix and discussion in this pull request: [https://github.com/labring/sealos/pull/2943](https://github.com/labring/sealos/pull/2943).

## 文件和目录位置问题
Therefore, if you encounter this problem, we recommend upgrading to Sealos version 4.2.0. The updated version should handle these changes correctly and not produce errors when adding a master node.

### Q1：如何修改`/root/.sealos`默认目录的存储位置？
## File and Directory Location Issues

若需修改默认的存储位置，可以设置SEALOS_RUNTIME_ROOT环境变量，然后运行sealos命令。建议您将这个环境变量设置为全局的，这样在其他命令或场景中也可以方便使用。
### Q1: How to modify the default storage location for `/root/.sealos`?

If you need to change the default storage location, you can set the `SEALOS_RUNTIME_ROOT` environment variable and then run the Sealos command. It is recommended to set this environment variable globally so that it can be conveniently used in other commands or scenarios.

```shell
export SEALOS_RUNTIME_ROOT=/data/.sealos
sealos run labring/kubernetes:v1.24.0
```

### Q2：如何修改`/var/lib/sealos`默认目录的存储位置？
### Q2: How to modify the default storage location for `/var/lib/sealos`?

若需修改默认的存储位置，可以设置SEALOS_DATA_ROOT环境变量，然后运行sealos命令。同样，建议您将这个环境变量设置为全局的。
If you need to change the default storage location, you can set the `SEALOS_DATA_ROOT` environment variable and then run the Sealos command. Similarly, it is recommended to set this environment variable globally.

```shell
export SEALOS_DATA_ROOT=/data/sealos
sealos run labring/kubernetes:v1.24.0
```

### Q3: 如何修改 Sealos 镜像数据和状态的存储路径?

> 在使用 Sealos 集群时，可能需要改变默认的镜像数据存储路径和状态数据的存储路径。默认情况下，这些数据被存储在 `/etc/containers/storage.conf` 文件定义的位置。
1. **查看当前存储配置**
首先，我们可以使用下面的命令来查看当前的镜像存储配置：
```
sealos images --debug
```
这个命令会打印出包含当前存储配置的文件，例如：
```
2023-06-07T16:27:02 debug using file /etc/containers/storage.conf as container storage config
REPOSITORY TAG IMAGE ID CREATED SIZE
```
2. **修改镜像数据存储路径**
如果你希望更改镜像数据的存储路径，你可以编辑 `/etc/containers/storage.conf` 文件。在这个文件中，找到并修改 `graphroot` 字段设置为新的路径。例如：
```
vim /etc/containers/storage.conf
```
在编辑器中，将 `graphroot` 字段的值修改为你希望的新路径。
3. **修改状态数据存储路径**
参考 Buildah 的设计，Sealos 同样提供了状态数据存储路径的设置。在同样的配置文件 `/etc/containers/storage.conf` 中，找到并修改 `runroot` 字段为新的路径。

通过以上步骤，你可以将 Sealos 集群的镜像数据和状态数据保存到新的地址。每次运行 Sealos 命令时，它都将使用你在 `graphroot` 和 `runroot` 中设置的新路径来分别存储镜像数据和状态数据。

### Q4：ssh传输文件时，如何禁止检查文件的md5？
### Q3: How to modify the storage paths for Sealos image data and status?

在网络环境良好时，禁用md5检查可以极大提升传输速度。若不想在ssh传输文件时检查文件的md5，可将SEALOS_SCP_CHECKSUM环境变量设置为false以禁用此功能。建议将此环境变量设为全局，以便在多场景下使用。
> When using the Sealos cluster, you may need to change the default storage paths for image data and status data. By default, these data are stored at the locations defined in the `/etc/containers/storage.conf` file.
```shell
export SEALOS_SCP_CHECKSUM=false
sealos run labring/kubernetes:v1.24.0
```
1. **View the current storage configuration**
First, you can use the following command to view the current image storage configuration:
```
sealos images --debug
```
This command will print the file that contains the current storage configuration, for example:
```
2023-06-07T16:27:02 debug using file /etc/containers/storage.conf as container storage config
REPOSITORY TAG IMAGE ID CREATED SIZE
```
2. **Modify the storage path for image data**
If you want to change the storage path for image data, you can edit the `/etc/containers/storage.conf` file. In this file, find and modify the `graphroot` field to set it to the new path. For example:
```
vim /etc/containers/storage.conf
```
In the editor, modify the value of the `graphroot` field to the desired new path.
3. **Modify the storage

path for status data**
Similar to the design of Buildah, Sealos also provides the ability to set the storage path for status data. In the same configuration file `/etc/containers/storage.conf`, find and modify the `runroot` field to the new path.

## 其他问题
By following these steps, you can save the image data and status data of the Sealos cluster to the new paths you set. Each time you run a Sealos command, it will use the new paths you set in `graphroot` and `runroot` to store the image data and status data, respectively.

### Q1：image-cri-shim导致端口大量占用，耗尽服务器socket资源？
### Q4: How to disable file md5 check during SSH file transfer?

出现此问题时，可通过以下命令解决：
When the network environment is good, disabling the md5 check can greatly improve transfer speed. If you don't want to check the md5 of files during SSH file transfer, you can add the `-o "HashKnownHosts no"` option to the SSH command.

```shell
wget https://github.com/labring/sealos/releases/download/v4.2.0/sealos_4.2.0_linux_amd64.tar.gz && tar xvf sealos_4.2.0_linux_amd64.tar.gz image-cri-shim
sealos exec -r master,node "systemctl stop image-cri-shim"
sealos scp "./image-cri-shim" "/usr/bin/image-cri-shim"
sealos exec -r master,node "systemctl start image-cri-shim"
sealos exec -r master,node "image-cri-shim -v"
scp -o "HashKnownHosts no" local_file remote_user@remote_ip:/path/to/destination
```

### Q2：报错"[ERROR FileAvailable--etc-kubernetes-kubelet.conf]: /etc/kubernetes/kubelet.conf already exists"

此问题可通过升级至Sealos 4.1.7+来解决。

### Q3：报错："function "semverCompare" not defined"

此问题可通过升级至Sealos 4.1.4+来解决。

我们希望这些解答能帮助您解决在使用Sealos过程中遇到的问题。如果还有其他问题，欢迎随时提问。

## 使用技巧

### Q1: 如何清理 Sealos 集群的缓存文件

> 在使用 Sealos 集群时，安装过程中可能会在本地存储一些缓存文件，这些文件会重复占用磁盘空间。那么，如何清理这些缓存文件以释放磁盘空间呢？
我们提供了一个非常简单的解决方案，只需要执行以下命令：

```shell
sealos unmount --all && sealos rm --all
```
这个命令的作用是移除所有缓存的 Sealos 集群镜像文件，以及所有的相关挂载点。--all 选项表示处理所有相关文件和挂载点。
执行这个命令后，所有 Sealos 集群的缓存文件就会被清理掉，从而释放出被它们占用的磁盘空间。
这是一个非常有用的技巧，特别是对于在磁盘空间有限的环境中运行 Sealos 集群的用户来说。在你感觉磁盘空间被占用过多时，不妨尝试执行这个命令来释放一些空间。
请注意，这个命令只会删除缓存文件，不会影响已经运行的集群。也就是说，执行这个命令后，你的集群仍然可以正常运行。
This option tells SSH not to hash the hostnames in the known_hosts file, which avoids the md5 check during file transfer.
56 changes: 29 additions & 27 deletions ...4.0/docs/lifecycle-management/advanced-guide/build-image-using-registry-sync.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,57 +2,57 @@
sidebar_position: 2
---

# 镜像构建改进指南
# Guide to Image Building Improvement

## 深入理解Sealos镜像构建
## Deep Understanding of Sealos Image Building

为了了解Sealos镜像构建的背后所做的工作，我们将首先揭示它在底层究竟进行了哪些操作。以下是一个直观的架构图：
To understand the work behind Sealos image building, we will first reveal what operations it actually performs at the underlying level. Here is an intuitive architectural diagram:

![](images/build.png)

Sealos在构建镜像过程中涵盖了以下几个核心步骤：
Sealos covers the following core steps in the image building process:

- **缓存镜像**：解析构建执行时的工作目录（在这里我们称之为"context"目录），将缓存镜像保存到registry结构并存储在./registry目录下。
- **构建镜像**：在context目录中进行镜像构建，生成新的镜像。（请注意，构建镜像时需要将./registry目录进行复制。）
- **Cache images**: Parse the working directory during the build execution (here we call it the "context" directory), save the cache image to the registry structure, and store it in the ./registry directory.
- **Build images**: Build images in the context directory and generate new images. (Please note, you need to copy the ./registry directory when building images.)

## 提升镜像构建效率
## Enhancing Image Building Efficiency

当前项目中，我们借用了`github.com/distribution/distribution`的源代码，在执行缓存镜像的过程中直接调用了registry的sdk并启动了registry-proxy功能。借助于镜像仓库的缓存能力，我们将镜像缓存并存入context/registry目录。
In the current project, we have borrowed the source code of `github.com/distribution/distribution`. During the process of caching images, we directly call the registry's sdk and start the registry-proxy function. With the caching ability of the image repository, we cache the image and store it in the context/registry directory.

这个过程的关键就在于调用了distribution仓库的方法进行保存镜像：
The key to this process is to call the method of the distribution repository to save the image:

- 启动 registry-proxy 功能。
- 保存镜像摘要及索引相关数据（通过调用saveManifestAndGetDigest方法）。
- 保存镜像文件数据（通过调用saveBlobs方法）。
- Start the registry-proxy function.
- Save image digest and related index data (by calling the saveManifestAndGetDigest method).
- Save image file data (by calling the saveBlobs method).

这种方法确实具有一些显著的优点：
This method does have some significant advantages:

- 轻量化：无需依赖其他组件即可保存镜像。
- 自由控制：可以自由控制保存逻辑，无需依赖第三方组件。
- Lightweight: Images can be saved without relying on other components.
- Free control: You can freely control the save logic without relying on third-party components.

然而，我们也注意到了一些潜在的问题：
However, we have also noticed some potential problems:

- 对新手来说，代码理解难度较高，不易清晰了解这里的逻辑。
- 无法缓存使用token认证的方式。
- 需要依赖一些临时存储空间，对空间有要求。
- For beginners, the code is difficult to understand and the logic here is not easy to grasp.
- Unable to cache using the token authentication method.
- Need to rely on some temporary storage space, which requires space.

考虑到这些问题，我们决定尝试一种新的模式：在本地启动一个轻量的registry，使用`skopeo copy`的sdk进行代码复用。这一改变直接解决了之前所有的问题。
Considering these issues, we decided to try a new mode: start a lightweight registry locally and use the sdk of `skopeo copy` for code reuse. This change directly solves all the previous problems.

![](images/registry-build.png)

**所以，新的构建方式 ✨镜像仓库同步✨ 优雅登场 🎉🎉**
**Therefore, the new construction method ✨Image Repository Sync✨ gracefully debuts 🎉🎉**

官方仓库中的[#3154](https://github.com/labring/sealos/pull/3154)这个PR已经完成了这个功能的实现。目前，Sealos支持这两种方式进行镜像构建。接下来，我会介绍如何启动新功能（如果新功能表现稳定，我们可能会废弃旧的构建方式）。
The [#3154](https://github.com/labring/sealos/pull/3154) PR in the official repository has completed the implementation of this feature. Currently, Sealos supports these two ways of image construction. Next, I will introduce how to start the new feature (if the new feature performs stably, we may abandon the old construction method).

## 如何启动新功能
## How to Start the New Feature

启动新功能非常简单，只需在你构建镜像之前添加一个环境变量即可。这个功能同时支持build和merge两个命令。
Starting the new feature is very simple, just add an environment variable before you build the image. This feature supports both build and merge commands.

```shell
SEALOS_REGISTRY_SYNC_EXPERIMENTAL=true sealos build -t test .
```

以下是执行上述命令后的预期输出：
Here is the expected output after executing the above command:

```tex
SEALOS_REGISTRY_SYNC_EXPERIMENTAL=true sealos build -t test .
Expand All @@ -75,9 +75,11 @@ Copying blob 13ab73c881c8 done
Copying config 4e22d16b36 done
Writing manifest to image destination
Storing signatures
--> 4e22d16b366
--> 4e22d16
b366
Successfully tagged localhost/test:latest
4e22d16b366e9fec25641522a74cbd73a7db67dc0516b8f8e00200c4d0551592
```

希望以上内容可以帮助您更好地理解并使用Sealos的新镜像构建方式。
I hope the above content can help you better understand and use Sealos's new image building method.
Loading

0 comments on commit 8110c77

Please sign in to comment.