Skip to content

Instantly share code, notes, and snippets.

@dims
Created October 21, 2026 19:21
Show Gist options
  • Select an option

  • Save dims/dd78680b549aca38dd60ec0c8a2c6200 to your computer and use it in GitHub Desktop.

Select an option

Save dims/dd78680b549aca38dd60ec0c8a2c6200 to your computer and use it in GitHub Desktop.
How `k8s.io` and `sigs.k8s.io` Serve Go Vanity Imports

How k8s.io and sigs.k8s.io Serve Go Vanity Imports

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.


1. The problem being solved

When you run go get k8s.io/client-go, the Go tool:

  1. Issues GET https://k8s.io/client-go?go-get=1
  2. Parses the HTML for <meta name="go-import" content="k8s.io/client-go git https://github.com/kubernetes/client-go">
  3. 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.


2. Architecture at a glance

                 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

3. The nginx config: k8s.io/<repo>

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 always git; 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 says master; most Kubernetes repos have master as the default branch, and GitHub redirects tree/master to 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.


4. The nginx config: sigs.k8s.io/<repo>

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_name lists both sigs.k8s.io and sigs.kubernetes.io, but the go-import tag always declares sigs.k8s.io/.... That is correct: the import path in go.mod is sigs.k8s.io/<repo>, and the alias domain simply serves the same answer.
  • Non-go-get requests go to GitHub, not to a website. sigs.k8s.io/kind lands on the repo; sigs.k8s.io/kind/site/README.md lands on github.com/kubernetes-sigs/kind/blob/master/site/README.md. This makes sigs.k8s.io/<repo>/<path> usable as a human-readable deep link in docs and chat.
  • The $repo_root juggling exists only because nginx if cannot express A || B.

5. Kubernetes manifests

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 key nginx.conf becomes /etc/nginx/nginx.conf. There is no conf.d/, no mime.types include.
  • maxUnavailable: 0 plus readiness probes means a config rollout never drops below three serving pods.
  • preStop: nginx -s quit asks nginx for a graceful shutdown so in-flight go get requests 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}}}
  • defaultBackend only, no rules: every hostname on the LB goes to the same nginx, and nginx's server_name blocks 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-name pins the LB to a reserved IP, so the DNS A records (34.107.204.206) never change across recreations. A separate -v6 Ingress on a reserved IPv6 address provides 2600: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_from block 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 total

One 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.


6. DNS

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.


7. Testing

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:

  1. HTTP ?go-get=1 must 301 to HTTPS, and HTTPS ?go-get=1 must 200. Redirecting the HTTPS request would break go get.
  2. Random repo names must work. example-test-repo and rand_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.


8. Deployment flow

deploy.sh (the deploy() function):

  1. Resolves the kube context for cluster aaa in project kubernetes-public, region us-central1 (fetching credentials if needed).
  2. kubectl apply the two ConfigMaps, Deployment and Service into namespace k8s-io-canary.
  3. kubectl rollout restart deployment k8s-io — required because ConfigMap changes do not restart pods on their own.
  4. Polls the Deployment until readyReplicas == spec.replicas and unavailableReplicas == 0.
  5. Reads every IP off the Ingress status and runs make test TARGET_IP=<ip> against each.
  6. 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.


9. Design trade-offs

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.


10. Reusing the pattern

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.


References

Repository: https://github.com/kubernetes/k8s.io (sig-k8s-infra)

Vanity redirector app, apps/k8s-io/:

DNS:

Cluster and project context:

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment