A walkthrough of the Kubernetes project's vanity-import redirector, as it exists in
kubernetes/k8s.io under apps/k8s-io/
(checked against main at commit 7753da3e, 2026-10-21). All file links below point
at main; line numbers were correct at that commit and may drift.
Every import "k8s.io/client-go/..." and import "sigs.k8s.io/kind/..." in the Go
ecosystem resolves through this setup. It is remarkably small: one nginx config, one
Deployment, one Ingress, one managed certificate, and a Python test file.
When you run go get k8s.io/client-go, the Go tool:
- Issues
GET https://k8s.io/client-go?go-get=1 - Parses the HTML for
<meta name="go-import" content="k8s.io/client-go git https://github.com/kubernetes/client-go"> - Clones the repository named in that tag
So the vanity domain's only job is to answer that one request with the right meta tag.
Everything else on k8s.io (humans browsing, docs, blog, release downloads) is handled
by ordinary redirects to kubernetes.io or GitHub.
The Kubernetes design decision that shapes everything else: the GitHub org is the
registry. There is no list of repositories anywhere. The domain maps k8s.io/<name>
to github.com/kubernetes/<name> purely by pattern, and sigs.k8s.io/<name> to
github.com/kubernetes-sigs/<name>. Creating a new repo in the org makes the vanity
path work with no infrastructure change.
DNS (octodns, dns/zone-configs/)
k8s.io A 34.107.204.206 "Our vanity redirector, hosted in GKE"
sigs.k8s.io CNAME redirect.k8s.io.
redirect.k8s.io A 34.107.204.206 / AAAA 2600:1901:0:26f3::
|
v
GCE global HTTPS load balancer (Ingress class "gce", static IPs, managed certs)
- terminates TLS, ~60 SANs on one ManagedCertificate
- forwards plain HTTP to pods with X-Forwarded-Proto: https
|
v
GKE cluster "aaa" (project kubernetes-public, us-central1)
namespace k8s-io-prod (and k8s-io-canary)
Deployment k8s-io: 3x nginx:1.30.1-alpine, config from a ConfigMap
Service k8s-io: ClusterIP with NEG annotation (LB talks to pods directly)
|
v
nginx.conf
server k8s.io -> regex location, emits go-import or 301 to kubernetes.io
server sigs.k8s.io -> regex location, emits go-import or 301 to GitHub
~25 other server blocks for apt., docs., git., go., rel., ... redirects
Files in apps/k8s-io/:
| File | Purpose |
|---|---|
configmap-nginx.yaml |
The entire nginx config, as a ConfigMap key nginx.conf |
configmap-www-get.yaml |
Static files served at get.k8s.io (install script); not vanity-related |
deployment.yaml |
3-replica nginx Deployment mounting the two ConfigMaps |
service.yaml |
ClusterIP service with cloud.google.com/neg for container-native LB |
ingress-prod.yaml, ingress-prod-v6.yaml |
GCE Ingress on reserved static IPv4 and IPv6 addresses |
ingress-canary.yaml, ingress-canary-v6.yaml |
Same for the canary namespace |
certificate-prod.yaml, certificate-canary.yaml |
GKE ManagedCertificate listing every hostname |
test.py, Dockerfile-test, Makefile |
Black-box tests run against a load-balancer IP |
deploy.sh |
kubectl apply + rollout wait + run tests, canary then prod |
README.md |
Table of all vanity hostnames and go.k8s.io/* short links |
This is the heart of it. Lightly reformatted from
configmap-nginx.yaml lines 20–75:
server {
server_name k8s.io;
listen 80 default_server;
location = /_healthz {
add_header Content-Type text/plain;
return 200 'ok';
}
# (two exact-match locations for /promo-tools/... attestation URLs omitted)
# NOTE: subpath is not currently used.
location ~ ^/(?<repo>[A-Za-z0-9\-_\.]*)(?<subpath>/.*)?$ {
# $https is set to 'on' when connecting to nginx via HTTPS directly.
set $https_status $https;
if ($http_x_forwarded_proto = 'https') {
set $https_status 'on';
}
# Upgrade HTTP to HTTPS.
if ($https_status != 'on') {
return 301 https://$host$request_uri;
}
if ($arg_go-get = "1") {
# This is a go-get operation.
return 200 '
<html><head>
<meta name="go-import"
content="k8s.io/$repo
git https://github.com/kubernetes/$repo">
<meta name="go-source"
content="k8s.io/$repo
https://github.com/kubernetes/$repo
https://github.com/kubernetes/$repo/tree/master{/dir}
https://github.com/kubernetes/$repo/blob/master{/dir}/{file}#L{line}">
</head></html>
';
}
# Default to redirecting to the "real" site.
return 301 https://kubernetes.io$request_uri;
}
}Reading it line by line:
The regex location. ^/(?<repo>[A-Za-z0-9\-_\.]*)(?<subpath>/.*)?$ captures the
first path segment as $repo and anything after it as $subpath. The character class
is deliberately narrow: letters, digits, -, _, .. That is exactly what GitHub
allows in a repo name, and it means $repo can be interpolated into a URL without any
escaping concerns. Note the * rather than +: an empty first segment (a request for
/) also matches and falls through to the final redirect.
Why $subpath is captured but unused. Go walks up the import path. For
k8s.io/apimachinery/pkg/runtime, it requests k8s.io/apimachinery/pkg/runtime?go-get=1,
and the response declares the module root k8s.io/apimachinery. Go accepts any
response whose declared prefix is a prefix of the requested path, so one response per
first segment covers every subpackage. Capturing $subpath just makes the regex match
the full path.
The HTTPS upgrade dance. TLS terminates at the GCE load balancer, so nginx only
ever sees listen 80. The $https variable is empty on those connections. The config
synthesises $https_status from $https or the X-Forwarded-Proto header the LB
adds, and 301s to https:// if neither says HTTPS. This matters for go get: Go
refuses to use go-import from a plain-HTTP response unless -insecure/GOINSECURE
is set, so an HTTP request must be redirected, never answered.
The go-get=1 branch. $arg_go-get is nginx's built-in accessor for the
go-get query parameter. When it equals "1", nginx returns a 200 with an inline
HTML body. return 200 '...' with a multi-line single-quoted string is legal nginx
syntax; the whitespace inside the content attributes is harmless because the Go tool
splits the attribute on whitespace.
Two meta tags are emitted:
go-import:k8s.io/$repo git https://github.com/kubernetes/$repo— the required one. VCS is alwaysgit; the clone URL is HTTPS.go-source: tells pkg.go.dev and godoc-style tools where the source browser lives, with{/dir},{file}and{line}templates. Note it still saysmaster; most Kubernetes repos havemasteras the default branch, and GitHub redirectstree/masterto the default branch anyway.
Everything else is a 301. A browser hitting https://k8s.io/blog/foo is sent to
https://kubernetes.io/blog/foo. The vanity domain carries no content of its own.
No Content-Type is set on the 200. nginx defaults return bodies to the
default_type, which is text/plain unless configured. The Go tool does not check
the content type when parsing go-import tags, so this works, but it is a small
wrinkle worth knowing if you copy the pattern and want browsers to render the page.
The second vanity namespace (configmap-nginx.yaml lines 118–168)
maps to a different GitHub org and is friendlier to humans:
# Vanity redirects for the new kubernetes-sigs repos
server {
server_name sigs.k8s.io sigs.kubernetes.io;
listen 80;
location ~ ^/(?<sig_repo>[A-Za-z0-9\-_\.]*)(?<repo_subpath>/.*)?$ {
# ... same HTTPS-upgrade block as above ...
if ($arg_go-get = "1") {
return 200 '
<html><head>
<meta name="go-import"
content="sigs.k8s.io/$sig_repo
git https://github.com/kubernetes-sigs/$sig_repo">
<meta name="go-source"
content="sigs.k8s.io/$sig_repo
https://github.com/kubernetes-sigs/$sig_repo
https://github.com/kubernetes-sigs/$sig_repo/tree/master{/dir}
https://github.com/kubernetes-sigs/$sig_repo/blob/master{/dir}/{file}#L{line}">
</head></html>
';
}
# nginx config syntax doesn't have an OR operator.
set $repo_root 0;
if ($repo_subpath = "/") {
set $repo_root 1;
}
if ($repo_subpath = "") {
set $repo_root 1;
}
if ($repo_root) {
# This is a regular request for https://sigs.k8s.io/<repo>
# Redirect to repo landing page, retain the trailing slash if present.
return 301 https://github.com/kubernetes-sigs/$sig_repo$repo_subpath;
}
# Default to redirecting to files in the tree.
return 301 https://github.com/kubernetes-sigs/$sig_repo/blob/master$repo_subpath;
}
}Differences from the k8s.io block:
server_namelists bothsigs.k8s.ioandsigs.kubernetes.io, but thego-importtag always declaressigs.k8s.io/.... That is correct: the import path ingo.modissigs.k8s.io/<repo>, and the alias domain simply serves the same answer.- Non-
go-getrequests go to GitHub, not to a website.sigs.k8s.io/kindlands on the repo;sigs.k8s.io/kind/site/README.mdlands ongithub.com/kubernetes-sigs/kind/blob/master/site/README.md. This makessigs.k8s.io/<repo>/<path>usable as a human-readable deep link in docs and chat. - The
$repo_rootjuggling exists only because nginxifcannot expressA || B.
Deployment (deployment.yaml)
replicas: 3
strategy: {type: RollingUpdate, rollingUpdate: {maxSurge: 1, maxUnavailable: 0}}
containers:
- name: nginx
image: nginx:1.30.1-alpine@sha256:6525b050... # pinned by digest
resources: {limits: {cpu: 1, memory: 512Mi}}
livenessProbe: httpGet {path: /_healthz, port: 80}
readinessProbe: httpGet {path: /_healthz, port: 80}
lifecycle:
preStop:
exec: {command: [/usr/sbin/nginx, -s, quit]} # graceful drain
volumeMounts:
- {name: nginx, mountPath: /etc/nginx, readOnly: true}
- {name: www-get, mountPath: /www/get, readOnly: true}
volumes:
- {name: nginx, configMap: {name: nginx}}
- {name: www-get, configMap: {name: www-get}}Points of note:
- The ConfigMap is mounted over all of
/etc/nginx, replacing the stock image config entirely. The ConfigMap's single keynginx.confbecomes/etc/nginx/nginx.conf. There is noconf.d/, nomime.typesinclude. maxUnavailable: 0plus readiness probes means a config rollout never drops below three serving pods.preStop: nginx -s quitasks nginx for a graceful shutdown so in-flightgo getrequests complete during rollouts.- The image is pinned to an exact digest. This is a stock upstream nginx; the project builds no custom image for this service.
Service and Ingress (service.yaml, ingress-prod.yaml)
# service.yaml
annotations:
cloud.google.com/neg: '{"ingress": true}'
type: ClusterIP
ports: [{name: http, port: 80}]# ingress-prod.yaml
annotations:
kubernetes.io/ingress.global-static-ip-name: k8s-io-ingress-prod
kubernetes.io/ingress.class: gce
networking.gke.io/managed-certificates: k8s-io-prod
spec:
defaultBackend: {service: {name: k8s-io, port: {name: http}}}defaultBackendonly, norules: every hostname on the LB goes to the same nginx, and nginx'sserver_nameblocks do the host routing. This keeps host logic in one place (the nginx config) rather than split between Ingress rules and nginx.global-static-ip-namepins the LB to a reserved IP, so the DNS A records (34.107.204.206) never change across recreations. A separate-v6Ingress on a reserved IPv6 address provides2600:1901:0:26f3::.- The NEG annotation makes the GCE LB send traffic straight to pod IPs, skipping
kube-proxy. This also means nginx sees the LB as the client, which is why the
config has a
set_real_ip_fromblock for the GCP LB ranges.
Certificate (certificate-prod.yaml)
apiVersion: networking.gke.io/v1
kind: ManagedCertificate
spec:
domains:
- k8s.io
- sigs.k8s.io
- sigs.kubernetes.io
- apt.k8s.io
- ... # ~60 hostnames in totalOne Google-managed certificate with every redirector hostname as a SAN. Adding a new
vanity subdomain is a three-line change: a DNS record, a server block, and a
domains entry. The canary environment instead uses a tls.secretName on its
Ingress (a cert-manager issued certificate) because managed certs require the real
production hostnames.
Managed with octodns from
dns/zone-configs/k8s.io._0_base.yaml
(apex at line 2, redirect at line 47, sigs at line 358):
'':
- type: A
value: 34.107.204.206 # Our vanity redirector, hosted in GKE
- type: AAAA
value: "2600:1901:0:26f3::"
redirect:
- type: A
value: 34.107.204.206
- type: AAAA
value: "2600:1901:0:26f3::"
sigs:
type: CNAME
value: redirect.k8s.io.The apex k8s.io must be A/AAAA records (no CNAME at apex). Every other redirector
hostname (sigs, sbom, docs, git, ...) is a CNAME to redirect.k8s.io, roughly
30 of them, so if the LB IP ever changes only two records need editing. The comment
in the zone file says this indirection was added precisely to keep the redirector IP
separable from the main record.
test.py is a black-box suite run with TARGET_IP=<lb ip> ./test.py. It opens raw
http.client connections to the IP, sets the Host header, and for HTTPS manually
wraps the socket with server_hostname so certificate verification still happens
against the real hostname even though it connected by IP. That lets the same tests
run against prod, canary, or a local docker run of the config.
The vanity-relevant assertions (test_go_get, test_sig_urls, test_protocol_upgrade):
def test_go_get(self):
self.assert_scheme_redirect(
'http://k8s.io/kubernetes?go-get=1',
'https://k8s.io/kubernetes?go-get=1', 301)
self.assert_code('https://k8s.io/kubernetes?go-get=1', 200)
# automatic redirects that aren't hard-coded
for url in ('sigs.k8s.io',):
self.assert_scheme_redirect(
'http://' + url + '/example-test-repo?go-get=1',
'https://' + url + '/example-test-repo?go-get=1', 301)
self.assert_code('https://' + url + '/example-test-repo?go-get=1', 200)
def test_sig_urls(self):
for base in ('https://sigs.k8s.io', 'https://sigs.kubernetes.io'):
self.assert_scheme_redirect(base + '/$sig_repo',
'https://github.com/kubernetes-sigs/$sig_repo', 301, sig_repo=rand_num())
self.assert_scheme_redirect(base + '/$sig_repo/$repo_subpath',
'https://github.com/kubernetes-sigs/$sig_repo/blob/master/$repo_subpath',
301, sig_repo=rand_num(), repo_subpath=rand_num())Two things the tests encode that are easy to get wrong:
- HTTP
?go-get=1must 301 to HTTPS, and HTTPS?go-get=1must 200. Redirecting the HTTPS request would breakgo get. - Random repo names must work.
example-test-repoandrand_num()confirm the wildcard behaviour; nothing is hard-coded per repo.
There is a second, stricter check further down the file:
assert_body_go_get fetches
https://k8s.io/example-repo/pkg/subpath?go-get=1, parses the HTML with a small
HTMLParser subclass (GoMetaParser), and
asserts the exact go-import and go-source strings, including the subpath case.
It is invoked from a second method also named test_go_get;
because Python keeps the last definition of a duplicated method name, this stricter
version is the one that actually runs, and the simpler status-code version shown above
is shadowed. Both express the same contract.
The test file also parses configmap-nginx.yaml to enumerate the go.k8s.io/*
short-link redirects and checks each one, so the README table and the config cannot
silently diverge for those.
deploy.sh (the deploy() function):
- Resolves the kube context for cluster
aaain projectkubernetes-public, regionus-central1(fetching credentials if needed). kubectl applythe two ConfigMaps, Deployment and Service into namespacek8s-io-canary.kubectl rollout restart deployment k8s-io— required because ConfigMap changes do not restart pods on their own.- Polls the Deployment until
readyReplicas == spec.replicasandunavailableReplicas == 0. - Reads every IP off the Ingress status and runs
make test TARGET_IP=<ip>against each. - Repeats steps 2–5 for
k8s-io-prod.
Running ./deploy.sh with no argument does canary then prod; ./deploy.sh prod or
./deploy.sh canary targets one. Ingress and certificate manifests are not applied
by this script; they change rarely and are applied by hand.
Wildcard org mapping.
Upside: zero per-repo config, new repos work instantly. Downside: k8s.io/does-not-exist?go-get=1
returns a well-formed go-import pointing at a nonexistent GitHub repo. The failure
surfaces as a git clone error rather than a 404, which is slightly confusing but
harmless. It also means the vanity domain can never host a module that lives outside
the org without adding an exact-match location above the regex.
Stock nginx, config in a ConfigMap, no custom image.
Upside: nothing to build, review is a YAML diff, rollback is git revert + redeploy.
Downside: nginx if is awkward (see the $repo_root workaround), and inline HTML in
single-quoted strings is unlovely. For two namespaces it is fine; a third org would
copy-paste a third server block.
TLS at the load balancer, HTTP to pods.
Upside: managed certificates, no key material in the cluster, one cert for ~60 hosts.
Downside: the X-Forwarded-Proto logic must exist and must be tested, because a
misconfiguration would either answer go get over HTTP (ignored by Go) or
redirect-loop.
Host routing in nginx, not in Ingress rules. Upside: one file describes every hostname's behaviour; the Ingress never changes. Downside: the Ingress gives no hint which hosts are served; you read the config.
Default branch hard-coded as master in go-source.
Works today because GitHub redirects, but it is a latent papercut for repos whose
default branch is main. The go-import tag is unaffected since it only names the
repo.
To clone this for your own org, the minimum viable copy is one server block:
server {
server_name go.example.com;
listen 80;
location = /_healthz { return 200 'ok'; }
location ~ ^/(?<repo>[A-Za-z0-9\-_\.]*)(?<subpath>/.*)?$ {
if ($http_x_forwarded_proto != 'https') {
return 301 https://$host$request_uri;
}
if ($arg_go-get = "1") {
add_header Content-Type text/html;
return 200 '<html><head>
<meta name="go-import" content="go.example.com/$repo git https://github.com/YOUR-ORG/$repo">
<meta name="go-source" content="go.example.com/$repo https://github.com/YOUR-ORG/$repo https://github.com/YOUR-ORG/$repo/tree/HEAD{/dir} https://github.com/YOUR-ORG/$repo/blob/HEAD{/dir}/{file}#L{line}">
</head></html>';
}
return 301 https://github.com/YOUR-ORG/$repo$subpath;
}
}That runs unchanged in a stock nginx:alpine container on Cloud Run, App Runner, ECS,
or any Kubernetes with a TLS-terminating ingress, because all of those set
X-Forwarded-Proto. Keep the three things their tests insist on: HTTP redirects to
HTTPS, HTTPS ?go-get=1 returns 200, arbitrary repo names resolve.
If you run it somewhere TLS terminates in the container, drop the
X-Forwarded-Proto check and rely on $https directly, or you will redirect-loop.
Repository: https://github.com/kubernetes/k8s.io (sig-k8s-infra)
Vanity redirector app, apps/k8s-io/:
README.md— table of every redirector hostname andgo.k8s.io/*short linkconfigmap-nginx.yaml— the nginx configdeployment.yaml— image pin, preStop,/etc/nginxmountservice.yamlingress-prod.yaml,ingress-prod-v6.yaml,ingress-canary.yaml,ingress-canary-v6.yamlcertificate-prod.yaml,certificate-canary.yamltest.py,Dockerfile-test,Makefiledeploy.shOWNERS— who to ask
DNS:
dns/zone-configs/k8s.io._0_base.yamldns/README.md— how zones are pushed with octodns
Cluster and project context:
apps/README.md— the communityaaacluster and how apps are deployed to itrunning-in-community-clusters.md- Go's remote import path spec:
go help importpath(https://pkg.go.dev/cmd/go#hdr-Remote_import_paths)