Azure / Azure/azure-container-networking
chore: upgrade Go 1.24 → 1.26.5
- Dominant language
- Go
- Stars
- 434
- Forks
- 276
- Avg merge
- 5d 20h
- Merged PRs (30d)
- 33
Description
## Go Minor Version Upgrade: 1.24 → 1.26.5
**Current version:** `1.24` (go.mod: `1.24.1`)
**Target version:** `1.26.5` (`1.26.5-azurelinux3.0`)
**MCR image:** `mcr.microsoft.com/oss/go/microsoft/golang:1.26-azurelinux3.0`
**Image digest:** `sha256:1c77c1cbb5de52db3f119fe2efe7a938e734c08196bbe3ad94b3bdadbab926f9`
### Instructions for Copilot Agent
Use the `acn-go-version-bump` skill (`.github/skills/acn-go-version-bump/SKILL.md`).
**Step 0 (MANDATORY): Analyze MS Go Documentation**
Before making ANY code changes, read the pre-cached MS Go docs for version 1.26:
```bash
# Read pre-cached docs (fetched by copilot-setup-steps before firewall)
cat .github/ms-go-docs/README.md
cat .github/ms-go-docs/NocgoOpenSSL.md
cat .github/ms-go-docs/MigrationGuide.md
cat .github/ms-go-docs/UserGuide.md
cat .github/ms-go-docs/AdditionalFeatures.md
# Fallback if cache is missing (may fail behind firewall):
# gh api "repos/microsoft/go/contents/docs/go1.26.md?ref=microsoft/main" --jq '.content' | base64 -d
```
Produce a **Requirements Matrix** that cross-references the docs against this repo:
- Build environment: GOEXPERIMENT rules per CGO setting, build flags, GOTOOLCHAIN behavior
- Runtime: required system libraries, base image requirements, architecture limits
- Crypto/FIPS: which backend is selected, CGO requirements, API behavior changes
- Compatibility: deprecated APIs, module system changes, dependency support
**Include the Requirements Matrix in your PR description.**
**Step 1: Execute Changes (based on your analysis)**
1. Update `build/images.mk`: `GO_IMG` → `mcr.microsoft.com/oss/go/microsoft/golang:1.26-azurelinux3.0`
2. Update `go.mod` and tools module (`tools-go/go.mod` or `tools.go.mod`) — use `.1` minimum patch
3. Do NOT run `go mod tidy` — it times out in the agent environment. Existing go.sum files are valid.
4. Apply FIPS/crypto changes per your doc analysis (do NOT blindly reuse previous version's rules)
5. Update all SHA references (install-go.sh, bpf-prog, npm Dockerfiles)
6. Run `make dockerfiles`
7. Run `go build ./...` and `go vet ./...`
**Key dependency check:** Verify controller-runtime, client-go, and cilium support Go 1.26
### ⚠️ FIPS / System Crypto Requirements (CRITICAL — builds will FAIL without this)
Go 1.26 enables `systemcrypto` by default, which requires CGO on Linux.
**Reference:** https://github.com/microsoft/go/blob/microsoft/main/eng/doc/fips/README.md#usage-common-configurations
**You MUST set GOEXPERIMENT in EVERY build path:**
| Build Configuration | Required GOEXPERIMENT | Reason |
|---|---|---|
| Linux + CGO_ENABLED=1 | `systemcrypto` | Uses OpenSSL via dlopen (explicit, redundant but clear) |
| Linux + CGO_ENABLED=0 | `ms_nocgo_opensslcrypto` | Enables nocgo OpenSSL backend (default systemcrypto requires CGO and will FAIL) |
| Windows (any CGO) | (none needed) | CNG backend works without CGO |
**Steps:**
1. Add `GOEXPERIMENT=ms_nocgo_opensslcrypto` to ALL scripts/Dockerfiles/Makefiles with `CGO_ENABLED=0` on Linux
2. Add `GOEXPERIMENT=systemcrypto` to scripts/Dockerfiles with `CGO_ENABLED=1` (cilium-log-collector)
3. Remove `MS_GO_NOSYSTEMCRYPTO=1` from npm Dockerfiles and replace with `GOEXPERIMENT=ms_nocgo_opensslcrypto`
4. npm Dockerfiles use **plain Go tags** (e.g., `golang:1.26.4`) — do NOT add `-azurelinux3.0` suffix
5. npm/windows.Dockerfile builds on Linux (`--platform=linux/amd64`) — it STILL needs GOEXPERIMENT for CGO=0
6. Ensure `MARINER_DISTROLESS_IMG` in `build/images.mk` is `distroless/base`
7. In root Makefile: add `ACN_GOEXPERIMENT` variable, apply inline to all CGO=0 build commands
8. **DO NOT** leave CGO_ENABLED=0 builds without GOEXPERIMENT — they WILL fail with crypto errors
### Acceptance Criteria
- [ ] Requirements Matrix included in PR description
- [ ] All version sources updated consistently
- [ ] `go build ./...` passes
- [ ] `make dockerfiles` output matches committed files
- [ ] No new `replace` directives (unless necessary and explained)
- [ ] FIPS/crypto config correct per MS Go docs for THIS specific version
- [ ] **Backport PR created for `release/v1.7`**
### Backport to `release/v1.7`
After the master PR is complete, create a **second PR** targeting `release/v1.7`:
1. Check out `release/v1.7`
2. Apply the same Go version + SHA changes
3. If `release/v1.7` is missing prerequisites (based on your analysis), add those too
4. Run `make dockerfiles` and `go mod tidy` on that branch
5. Title: `chore(release/v1.7): upgrade Go 1.24 → 1.26.5`
6. Verify `go build ./...` passes on release branch
> **Note:** The release branch may have different dependency versions than master.
> Run `go mod tidy` separately and resolve any conflicts specific to that branch.
---
Contributor guide
Research direction
Start by reading .github/skills/acn-go-version-bump/SKILL.md and the cached files under .github/ms-go-docs/, then inspect build/images.mk, go.mod, the tools module, Makefile, install-go.sh, bpf-prog, and the npm Dockerfiles. Verify the documented Go 1.26 crypto and build requirements against every listed build path and dependency before changing versions and SHA references. Done means generated Dockerfiles match, builds and vet pass, the requirements matrix is in the PR, and the release/v1.7 backport PR is created.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- docker, go
- Domain
- build-system, devops, infrastructure
- Issue type
- Refactor
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Quiet
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100