v2.0.0

Release date: 2026-10-13.

This is the first stable release of the /v2 module. The SDK and CLI implementation is unchanged from v2.0.0-rc.1. It includes expanded resource APIs and the behavior changes below. Applications upgrading from v1.1.1 should review their source, saved encodings and CLI automation before testing against their target.

Compatibility

• The module is github.com/zhh2001/p4runtime-go-controller/v2. Update SDK imports to include /v2. Go 1.26 is required, with 1.26.0 as the minimum and 1.26.9 as the preferred toolchain.
• pre.Replica now contains byte ports and ordered backup replicas. It contains slices, so it cannot be compared with == or used as a map key. Use keyed literals for pre.Replica and meter.Config, whose fields have grown.
• Numeric zero is encoded as 00, including an LPM mask with a zero prefix. Check the prefix length for an LPM wildcard. Optional(nil) is a wildcard, while Optional([]byte{}) matches zero.
• Counter, meter and register reads use -1 to select all entries. Writes require a non-negative index. Ordinary indexes must fit the declared array size, while translated indexes remain subject to target validation.
• register.Reader.Write accepts bit<W> and int<W> values. Use WriteData for other supported P4Data types. Signed values use big-endian two's complement. Varbits retain their bytes and explicit bitwidth.
• Meter rates and bursts must be non-negative and satisfy the declared meter type. Replace the target-specific -1 default convention with Reset. An explicit zero configuration remains distinct from reset.

Follow the v2 migration guide for source examples and behavior checks. Links to this tag become available when the tag is public.

SDK changes

• Stream sends wait for gRPC send completion and return send errors. CloseGracefully(ctx) drains accepted sends, closes the sending side and waits for the final stream status. Send completion does not acknowledge target processing or packet forwarding. Use a deadline and call graceful close outside stream handlers.
• Disconnect and close revoke primary status. Concurrent BecomePrimary calls observe current mastership independently of Events. Stream callbacks can register or cancel subscriptions, with cancellation applying to future dispatches.
• errors.WriteError retains the original gRPC status and complete per-update results in request order. errors.Is matches any failed update. Use errors.As to inspect successful and failed indexes before retrying a partially successful batch.
• tableentry.Builder.BuildKey() builds keys for DELETE. Table validation checks required exact fields, widths, action membership and scope, priority, idle timeout and constant-table restrictions. LPM, ternary and range encodings follow the declared field width.
• PipelineCommit requires a nil pipeline and commits a previously saved configuration. Other actions require a pipeline. Automatic fallback is limited to VERIFY_AND_COMMIT trying RECONCILE_AND_COMMIT when the target reports an unsupported action.
• Pipeline constructors, Info, Raw and resource queries copy their messages. Compare resource IDs across queries. Edit a copy and construct a new Pipeline to change its definitions.
• PacketOut requires all metadata declared by P4Info, including padding. digest.Subscriber.Subscribe returns subscription validation errors. Digest ACKs require a declared nonzero digest ID and remain valid after cancellation.
• pre.Replica.Port and BackupReplicas preserve opaque port bytes and backup order. register.Reader.WriteData, meter.Config.EBurst and meter.Reader.Reset cover additional typed resource operations.
• WithLogger reports connection attempts, mastership, disconnects, retry delays and shutdown. Built-in metrics collectors and adapters remain planned.

CLI and local targets

The CLI supports certificate-verified TLS and mutual TLS with --insecure=false, --tls-ca, --tls-server-name, --tls-cert and --tls-key. Use --config-file or P4CTL_CONFIG_FILE for CLI settings. pipeline set --config continues to select the device configuration.

JSON and YAML output are available for connect, pipeline set/get, table read and counter read. Read results are arrays, including empty results. Protobuf bytes use base64 and 64-bit values use strings. Valid IPv6 takes precedence over colon-separated bytes. Use a 0x prefix for unambiguous raw bytes.

The BMv2 launcher uses native simple_switch_grpc by default and retains --docker. It compiles matching P4Info and device configuration, with device ID 1 and CPU port 255. The bundled L2 program sends table misses to PacketIn and counts by egress port. API documentation uses a shared index and one page per public package.

Installation

Select the stable version from your application module:

go get github.com/zhh2001/p4runtime-go-controller/v2@v2.0.0
go install github.com/zhh2001/p4runtime-go-controller/v2/cmd/p4ctl@v2.0.0

Remove a local SDK replace directive before using the published tag. Run go mod tidy after updating imports. A CLI installed from source normally reports dev. Use go version -m /absolute/path/to/p4ctl to inspect its module version.

CLI archives cover Linux and macOS on amd64 and arm64, plus Windows amd64. Archives include the executable, LICENSE, NOTICE and README, with an SPDX SBOM and signed checksum file. Archive binaries carry the release version, commit and build date. See archive installation.

Target support

A newer SDK does not add target capabilities. Byte ports require target support for P4Runtime 1.4, and backup replicas require P4Runtime 1.5. Register access, translated types and meter modes also depend on the target. Valid header varbits are unsupported by WriteData because P4Runtime headers do not carry their field bitwidths.

Use a dedicated target to validate the features your application needs. The integration guide describes the BMv2 suites and their requirements.

Security maintenance

Security maintenance remains on the v2.0 line. v1 maintenance ended when v2.0.0-rc.1 was published, under the security policy. Unreleased branches and draft GitHub releases do not advance that window.

The changelog contains the complete changes.