Mainland China network
⚠️ This chapter applies only to mainland China network environments. If the host can reach
docker.io,registry.k8s.ioandgcr.iodirectly (an overseas data center, or a proxy already configured), skip this entire chapter — pulling images and installing Istio need no extra configuration.
← Documentation index · Previous: Cluster preparation (MicroK8s) · Next: Install Istio
On a mainland China network, installing the cluster runs into two problems: images cannot be pulled (the K8s and
Istio component images live on docker.io / gcr.io), and the installer cannot be downloaded (GitHub releases,
curl | sh). This chapter handles both, each with the command that proves it worked.
1. First, confirm that you need this
sudo microk8s ctr images pull docker.io/library/nginx:alpine
curl -sI -m 10 https://registry.k8s.io/v2/ | head -1
If both commands succeed within a few seconds, the network is fine — go back to Install Istio. If they time out or sit there with no output, keep reading.
2. Configure image mirrors for containerd
The fix is to configure hosts.toml for containerd: no Docker restart and no change to each manifest.
SNAP_DATA=/var/snap/microk8s/current
CERTS_DIR=${SNAP_DATA}/args/certs.d
sudo mkdir -p "${CERTS_DIR}"
First make containerd aware of this directory:
sudo microk8s stop
sudo cp ${SNAP_DATA}/args/containerd-template.toml ${SNAP_DATA}/args/containerd-template.toml.bak
grep -q 'config_path' ${SNAP_DATA}/args/containerd-template.toml \
|| sudo sed -i '/plugins.*registry\]$/a\ config_path = "'"${CERTS_DIR}"'"' ${SNAP_DATA}/args/containerd-template.toml
sudo microk8s start
The section names in the template differ between MicroK8s versions (
registry/registry.configs). After writing, alwaysgrep config_pathand confirm there is exactly one entry pointing atcerts.d; writing it twice keeps containerd from starting, andmicrok8s statusstays stuck atwaiting.
Then write one hosts.toml per registry (the mirror list is replaceable; this is the combination with the most fallbacks):
write_mirror() {
local host=$1; shift
sudo mkdir -p "${CERTS_DIR}/${host}"
{ echo "server = \"https://${host}\""
for m in "$@"; do
printf '\n[host."%s"]\n capabilities = ["pull", "resolve"]\n' "$m"
done
} | sudo tee "${CERTS_DIR}/${host}/hosts.toml" > /dev/null
}
write_mirror docker.io \
https://docker.m.daocloud.io https://docker.mirrors.ustc.edu.cn https://mirror.baidubce.com
write_mirror registry.k8s.io https://k8s.m.daocloud.io https://registry.lank8s.cn
write_mirror gcr.io https://gcr.m.daocloud.io
write_mirror registry.istio.io https://gcr.m.daocloud.io
write_mirror quay.io https://quay.m.daocloud.io
write_mirror ghcr.io https://ghcr.m.daocloud.io
registry.istio.iois actually a service that redirects togcr.iobackend storage, so it needs its own entry — configuringgcr.ioalone is not enough, because image pulls addressregistry.istio.io.
Verify
Note --hosts-dir; without it ctr does not read these files:
sudo microk8s ctr images pull --hosts-dir ${CERTS_DIR} docker.io/library/nginx:alpine
sudo microk8s ctr images pull --hosts-dir ${CERTS_DIR} registry.k8s.io/pause:3.10
sudo microk8s ctr images rm docker.io/library/nginx:alpine
After a microk8s upgrade the current symlink points at the new version automatically, so the mirror configuration
usually needs no rework; if pulls fail again after an upgrade, first check whether certs.d is still there.
3. Install Istio: the archive and the images
Two separate things:
| Step | What to do on a mainland China network |
|---|---|
| Installer archive | Download the release archive on a machine that can reach GitHub, scp it to the target host; do not count on curl | sh |
| Images | Add --set hub=docker.io/istio when installing, so images come from Docker Hub (the mirrors from the previous section) |
# Download on a machine with internet access: https://github.com/istio/istio/releases
scp istio-1.30.0-linux-amd64.tar.gz <user>@<host>:/root/
tar -xzf istio-1.30.0-linux-amd64.tar.gz
cd istio-1.30.0
export PATH=$PWD/bin:$PATH
Before installing, confirm the image can be pulled, with --hosts-dir:
sudo microk8s ctr images pull --hosts-dir ${CERTS_DIR} docker.io/istio/pilot:1.30.0
Then install with the commands in section 2 of Install Istio.
4. Fully offline: an intranet registry or pre-imported images
When the host cannot reach any mirror at all, there are two options: stand up a registry on the intranet (Harbor, or a
minimal registry:2), sync the images into it, and point [host."..."] in hosts.toml at the intranet address; or
export individual images with docker save and import them into MicroK8s's containerd:
# Export on a machine with internet access
docker save istio/pilot:1.30.0 -o pilot.tar
# Import on the target node; MicroK8s keeps images in the k8s.io namespace
sudo microk8s ctr --namespace k8s.io images import pilot.tar
sudo microk8s ctr --namespace k8s.io images ls | grep pilot
Line the list of images up with Services and ports and the Bundle version you are installing;
miss one and the corresponding Pod goes ImagePullBackOff.