### Install the YAML package

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/go.yaml.in/yaml/v3/README.md

Use the go get command to add the package to your project.

```bash
go get go.yaml.in/yaml/v3
```

--------------------------------

### Install and Run Local Go Doc Site

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/go.opentelemetry.io/otel/CONTRIBUTING.md

Installs and runs a local Go Doc site using `pkgsite`. Ensure `golang.org/x/pkgsite/cmd/pkgsite` is installed.

```sh
go install golang.org/x/pkgsite/cmd/pkgsite@latest
pkgsite
```

--------------------------------

### Install Doublestar

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/bmatcuk/doublestar/README.md

Install the doublestar package using go get. This command fetches and installs the package and its dependencies.

```bash
go get github.com/bmatcuk/doublestar
```

--------------------------------

### Install gouuid Package

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/nu7hatch/gouuid/README.md

Use the 'go get' command to install the gouuid package. This command fetches and installs the specified package and its dependencies.

```bash
go get github.com/nu7hatch/gouuid
```

--------------------------------

### Installation

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/bmatcuk/doublestar/README.md

Instructions on how to install and import the doublestar package.

```APIDOC
## Installation

**doublestar** can be installed via `go get`:

```bash
go get github.com/bmatcuk/doublestar
```

To use it in your code, you must import it:

```go
import "github.com/bmatcuk/doublestar"
```
```

--------------------------------

### Example output

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/go.yaml.in/yaml/v3/README.md

The expected output generated by the provided Go example code.

```text
--- t:
{Easy! {2 [3 4]}}

--- t dump:
a: Easy!
b:
  c: 2
  d: [3, 4]


--- m:
map[a:Easy! b:map[c:2 d:[3 4]]]

--- m dump:
a: Easy!
b:
  c: 2
  d:
  - 3
  - 4
```

--------------------------------

### Ginkgo Spec Example

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/onsi/ginkgo/v2/README.md

This example demonstrates a typical Ginkgo spec structure, including BeforeEach, When, Context, It, and various Gomega matchers like Expect, Succeed, ContainElement, Equal, MatchError, BeEmpty, and Eventually. It also shows SpecTimeout and By for structuring tests.

```go
import (
    . "github.com/onsi/ginkgo/v2"
    . "github.com/onsi/gomega"
    ...
)

var _ = Describe("Checking books out of the library", Label("library"), func() {
    var library *libraries.Library
    var book *books.Book
    var valjean *users.User
    BeforeEach(func() {
        library = libraries.NewClient()
        book = &books.Book{
            Title: "Les Miserables",
            Author: "Victor Hugo",
        }
        valjean = users.NewUser("Jean Valjean")
    })

    When("the library has the book in question", func() {
        BeforeEach(func(ctx SpecContext) {
            Expect(library.Store(ctx, book)).To(Succeed())
        })

        Context("and the book is available", func() {
            It("lends it to the reader", func(ctx SpecContext) {
                Expect(valjean.Checkout(ctx, library, "Les Miserables")).To(Succeed())
                Expect(valjean.Books()).To(ContainElement(book))
                Expect(library.UserWithBook(ctx, book)).To(Equal(valjean))
            }, SpecTimeout(time.Second * 5))
        })

        Context("but the book has already been checked out", func() {
            var javert *users.User
            BeforeEach(func(ctx SpecContext) {
                javert = users.NewUser("Javert")
                Expect(javert.Checkout(ctx, library, "Les Miserables")).To(Succeed())
            })

            It("tells the user", func(ctx SpecContext) {
                err := valjean.Checkout(ctx, library, "Les Miserables")
                Expect(err).To(MatchError("Les Miserables is currently checked out"))
            }, SpecTimeout(time.Second * 5))

            It("lets the user place a hold and get notified later", func(ctx SpecContext) {
                Expect(valjean.Hold(ctx, library, "Les Miserables")).To(Succeed())
                Expect(valjean.Holds(ctx)).To(ContainElement(book))

                By("when Javert returns the book")
                Expect(javert.Return(ctx, library, book)).To(Succeed())

                By("it eventually informs Valjean")
                notification := "Les Miserables is ready for pick up"
                Eventually(ctx, valjean.Notifications).Should(ContainElement(notification))

                Expect(valjean.Checkout(ctx, library, "Les Miserables")).To(Succeed())
                Expect(valjean.Books(ctx)).To(ContainElement(book))
                Expect(valjean.Holds(ctx)).To(BeEmpty())
            }, SpecTimeout(time.Second * 10))
        })
    })

    When("the library does not have the book in question", func() {
        It("tells the reader the book is unavailable", func(ctx SpecContext) {
            err := valjean.Checkout(ctx, library, "Les Miserables")
            Expect(err).To(MatchError("Les Miserables is not in the library catalog"))
        }, SpecTimeout(time.Second * 5))
    })
})
```

--------------------------------

### Convert format-string logs to structured key-value pairs

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/go-logr/logr/README.md

Examples demonstrating the migration from klog format-string logging to structured logr-style logging.

```go
klog.V(4).Infof("Client is returning errors: code %v, error %v", responseCode, err)
```

```go
logger.Error(err, "client returned an error", "code", responseCode)
```

```go
klog.V(4).Infof("Got a Retry-After %ds response for attempt %d to %v", seconds, retries, url)
```

```go
logger.V(4).Info("got a retry-after response when requesting url", "attempt", retries, "after seconds", seconds, "url", url)
```

--------------------------------

### BOSH Deployment Manifest Example

Source: https://context7.com/cloudfoundry/bosh-docker-cpi-release/llms.txt

An example BOSH deployment manifest for utilizing the Docker CPI.

```APIDOC
## BOSH Deployment Manifest

### Description
Example deployment manifest for using Docker CPI with BOSH Director.

### Manifest Structure
```yaml
---
name: my-deployment

releases:
- name: my-release
  version: latest

stemcells:
- alias: default
  os: ubuntu-noble
  version: latest

instance_groups:
- name: web-server
  instances: 2
  azs: [z1]
  jobs:
  - name: web
    release: my-release
  vm_type: default
  stemcell: default
  networks:
  - name: default
  persistent_disk_type: 10GB

vm_types:
- name: default
  cloud_properties:
    ports:
    - "8080/tcp"
    - "443/tcp"
    force_start_with_systemd: true

disk_types:
- name: 10GB
  disk_size: 10240

networks:
- name: default
  type: manual
  subnets:
  - range: 10.244.0.0/24
    gateway: 10.244.0.1
    dns: [8.8.8.8]
    cloud_properties:
      name: my-docker-network

compilation:
  workers: 3
  reuse_compilation_vms: true
  az: z1
  vm_type: default
  network: default
```
```

--------------------------------

### Install Counterfeiter to GOPATH

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/maxbrunsfeld/counterfeiter/v6/README.md

Install the tool globally to allow invocation outside of a Go module.

```shell
$ go install github.com/maxbrunsfeld/counterfeiter/v6
$ ~/go/bin/counterfeiter

USAGE
	counterfeiter
		[-generate>] [-o <output-path>] [-p] [--fake-name <fake-name>]
		[-header <header-file>]
		[<source-path>] <interface> [-]
```

--------------------------------

### Get opentelemetry-go Project

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/go.opentelemetry.io/otel/CONTRIBUTING.md

Use 'go get' to download the opentelemetry-go project. This command may produce warnings that can be ignored.

```go
go get -d go.opentelemetry.io/otel
```

--------------------------------

### Deterministic Testing Setup for Observability

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/go.opentelemetry.io/otel/CONTRIBUTING.md

Set up deterministic testing by isolating the meter provider, using t.Setenv for environment variables, and resetting global state like component ID counters.

```go
func TestObservability(t *testing.T) {
	// Restore state after test to ensure this does not affect other tests.
    prev := otel.GetMeterProvider()
    t.Cleanup(func() {
        otel.SetMeterProvider(prev)
    })

    // Isolate the meter provider for deterministic testing
    reader := metric.NewManualReader()
    meterProvider := metric.NewMeterProvider(metric.WithReader(reader))
    otel.SetMeterProvider(meterProvider)

	// Use t.Setenv to ensure environment variable is restored after test.
    t.Setenv("OTEL_GO_X_OBSERVABILITY", "true")

	// Reset component ID counter to ensure deterministic component names.
	componentIDCounter.Store(0)
 
	/* ... test code ... */
}
```

--------------------------------

### BOSH Deployment Manifest Example

Source: https://context7.com/cloudfoundry/bosh-docker-cpi-release/llms.txt

An example BOSH deployment manifest for utilizing the Docker CPI release. It configures releases, stemcells, instance groups, VM types, disk types, and networks.

```yaml
---
name: my-deployment

releases:
- name: my-release
  version: latest

stemcells:
- alias: default
  os: ubuntu-noble
  version: latest

instance_groups:
- name: web-server
  instances: 2
  azs: [z1]
  jobs:
  - name: web
    release: my-release
  vm_type: default
  stemcell: default
  networks:
  - name: default
  persistent_disk_type: 10GB

vm_types:
- name: default
  cloud_properties:
    ports:
    - "8080/tcp"
    - "443/tcp"
    force_start_with_systemd: true

disk_types:
- name: 10GB
  disk_size: 10240

networks:
- name: default
  type: manual
  subnets:
  - range: 10.244.0.0/24
    gateway: 10.244.0.1
    dns: [8.8.8.8]
    cloud_properties:
      name: my-docker-network

compilation:
  workers: 3
  reuse_compilation_vms: true
  az: z1
  vm_type: default
  network: default
```

--------------------------------

### Update Semantic Convention Imports

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/go.opentelemetry.io/otel/RELEASING.md

Example of updating Go import paths to reference the newly generated semconv version.

```go
// Before
semconv "go.opentelemetry.io/otel/semconv/v1.37.0"
"go.opentelemetry.io/otel/semconv/v1.37.0/otelconv"


// After
semconv "go.opentelemetry.io/otel/semconv/v1.39.0"
"go.opentelemetry.io/otel/semconv/v1.39.0/otelconv"
```

--------------------------------

### Configure golangci-lint for VSCode

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/Microsoft/go-winio/README.md

Configure VSCode to use golangci-lint for package linting on save. Ensure golangci-lint is installed locally.

```json
    "go.lintTool": "golangci-lint",
    "go.lintOnSave": "package"
```

--------------------------------

### Define Go interface

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/maxbrunsfeld/counterfeiter/v6/README.md

Example interface definition used for generating a test double.

```go
package foo

type MySpecialInterface interface {
		DoThings(string, uint64) (int, error)
}
```

--------------------------------

### View Stemcells with Docker CPI

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/README.md

Example output showing stemcells managed by the Docker CPI. Note that the CID is the Docker image digest, ensuring immutability.

```bash
$ bosh stemcells
NAME                      VERSION  OS            CID
bosh-docker-ubuntu-noble  1.165    ubuntu-noble  ghcr.io/cloudfoundry/ubuntu-noble-stemcell@sha256:d4ca21a75f1ff6be382695e299257f054585143bf09762647bcb32f37be5eaf3
```

--------------------------------

### List all containers using the Docker Go client

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/docker/docker/client/README.md

Demonstrates initializing the client from environment variables and listing all containers, equivalent to the docker ps --all command.

```go
package main

import (
	"context"
	"fmt"

	"github.com/docker/docker/api/types/container"
	"github.com/docker/docker/client"
)

func main() {
	apiClient, err := client.NewClientWithOpts(client.FromEnv)
	if err != nil {
		panic(err)
	}
	defer apiClient.Close()

	containers, err := apiClient.ContainerList(context.Background(), container.ListOptions{All: true})
	if err != nil {
		panic(err)
	}

	for _, ctr := range containers {
		fmt.Printf("%s %s (status: %s)\n", ctr.ID, ctr.Image, ctr.Status)
	}
}
```

--------------------------------

### Implement Info Method

Source: https://context7.com/cloudfoundry/bosh-docker-cpi-release/llms.txt

Returns CPI capabilities and supported stemcell formats to the BOSH Director.

```go
// CPI Info response structure
type Info struct {
    StemcellFormats []string  // ["warden-tar", "general-tar", "docker-light"]
    APIVersion      int       // 2
}

// Example response
{
  "stemcell_formats": ["warden-tar", "general-tar", "docker-light"],
  "api_version": 2
}
```

--------------------------------

### Run mkall.sh to build for current OS/Arch (Old System)

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/golang.org/x/sys/unix/README.md

Use this command to generate Go files for your current OS and architecture when using the old build system. Ensure GOOS and GOARCH are set correctly.

```bash
mkall.sh
```

--------------------------------

### Instantiate with Options in Go

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/go.opentelemetry.io/otel/CONTRIBUTING.md

Demonstrates how to instantiate a type T using a variadic slice of Option. Required parameters can be passed before the options.

```go
func NewT(options ...Option) T {…}
```

--------------------------------

### Prepare and Commit Changes

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/go.opentelemetry.io/otel/CONTRIBUTING.md

Create a new branch, make your modifications, run precommit checks, stage changes, commit, and push to your fork.

```sh
git checkout -b <YOUR_BRANCH_NAME>
# edit files
# update changelog
make precommit
git add -p
git commit
git push <YOUR_FORK> <YOUR_BRANCH_NAME>
```

--------------------------------

### Create New Configuration with Options

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/go.opentelemetry.io/otel/CONTRIBUTING.md

Creates a new configuration by applying a variable number of options to a default `config` struct. This function is usually unexported.

```go
// newConfig returns an appropriately configured config.
func newConfig(options ...Option) config {
	// Set default values for config.
	config := config{/* […] */}
	for _, option := range options {
		config = option.apply(config)
	}
	// Perform any validation here.
	return config
}
```

--------------------------------

### Implement CreateVM / CreateVMV2 Method

Source: https://context7.com/cloudfoundry/bosh-docker-cpi-release/llms.txt

Creates a Docker container from a stemcell image with specified cloud properties and network configuration.

```go
// Function signature
func (a CreateVMMethod) CreateVMV2(
    agentID apiv1.AgentID,
    stemcellCID apiv1.StemcellCID,
    cloudProps apiv1.VMCloudProps,
    networks apiv1.Networks,
    diskCIDs []apiv1.DiskCID,
    env apiv1.VMEnv,
) (apiv1.VMCID, apiv1.Networks, error)

// VM cloud properties structure
type Props struct {
    ExposedPorts             []string `json:"ports"`                       // e.g., ["6868/tcp", "8080/tcp"]
    ForceStartWithSystemD    bool     `json:"force_start_with_systemd"`    // Use /sbin/init
    ForceStartWithoutSystemD bool     `json:"force_start_without_systemd"` // Use runsvdir
    ForceLXCFSEnabled        bool     `json:"force_lxcfs_enabled"`         // Enable LXCFS mounts
    ForceLXCFSDisabled       bool     `json:"force_lxcfs_disabled"`        // Disable LXCFS mounts
    // Supports all Docker HostConfig options inline
}

// Example deployment manifest cloud_properties
// instance_groups:
// - name: my-instance
//   vm_type: default
//   cloud_properties:
//     ports:
//     - "8080/tcp"
//     - "443/tcp"
//     force_start_with_systemd: true
```

--------------------------------

### BOSH Docker CPI error logs

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/docs/snippets.md

Example error messages encountered during disk attachment and VM creation operations.

```text
Attaching disk 'd5b88b2e-fab6-427e-71ef-61007a2dd317' to VM 'd15c95fc-d120-4460-7a1c-a4223fc0ad5c': Restarting by recreating: Disposing of container before disk attachment: Killing container: Error response from daemon: Container d15c95fc-d120-4460-7a1c-a4223fc0ad5c running on unhealthy node 4f9b707f-625c-4ae1-ae9c-0654e61ac6c1

Attaching disk 'd5b88b2e-fab6-427e-71ef-61007a2dd317' to VM '7198e9d7-120e-4e86-6693-55dd5162f027': Restarting by recreating: Disposing of container before disk attachment: Error response from daemon: Cannot connect to the docker engine endpoint

Creating VM with agent ID '44875d58-8705-4fe7-bc31-68b13f8f2994': Creating container: Error response from daemon: Container created but refresh didn't report it back
```

--------------------------------

### Show mkall.sh commands (Old System)

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/golang.org/x/sys/unix/README.md

This command displays the build commands that will be executed by mkall.sh without actually running them. Useful for understanding the build process.

```bash
mkall.sh -n
```

--------------------------------

### Run golangci-lint locally

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/Microsoft/go-winio/README.md

Execute golangci-lint from the repository root to check for linting errors. Use flags to control the number of issues reported.

```shell
# use . or specify a path to only lint a package
# to show all lint errors, use flags "--max-issues-per-linter=0 --max-same-issues=0"
> golangci-lint run ./...
```

--------------------------------

### Initialize Instrumentation Explicitly

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/go.opentelemetry.io/otel/CONTRIBUTING.md

Use constructor functions to initialize instrumentation, ensuring clear ownership and avoiding implicit side effects.

```go
import (
	"errors"

	semconv "go.opentelemetry.io/otel/semconv/v1.40.0"
	"go.opentelemetry.io/otel/semconv/v1.40.0/otelconv"
)

type SDKComponent struct {
    inst *instrumentation
}

func NewSDKComponent(config Config) (*SDKComponent, error) {
    inst, err := newInstrumentation()
    if err != nil {
        return nil, err
    }
    return &SDKComponent{inst: inst}, nil
}

type instrumentation struct {
    inflight otelconv.SDKComponentInflight
    exported otelconv.SDKComponentExported
}

func newInstrumentation() (*instrumentation, error) {
    if !x.Observability.Enabled() {
        return nil, nil
    }
 
    meter := otel.GetMeterProvider().Meter(
        "<component-package-name>",
        metric.WithInstrumentationVersion(sdk.Version()),
        metric.WithSchemaURL(semconv.SchemaURL),
    )

	inst := &instrumentation{}

	var err, e error
    inst.inflight, e = otelconv.NewSDKComponentInflight(meter)
	err = errors.Join(err, e)

    inst.exported, e = otelconv.NewSDKComponentExported(meter)
	err = errors.Join(err, e)

    return inst, err
}
```

```go
// ❌ Avoid this pattern.
func (c *Component) initObservability() {
	// Initialize observability metrics
	if !x.Observability.Enabled() {
		return
	}

	// Initialize observability metrics
	c.inst = &instrumentation{/* ... */}
}
```

--------------------------------

### Handle Overlapping Configurations with Interfaces in Go

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/go.opentelemetry.io/otel/CONTRIBUTING.md

Illustrates handling overlapping configurations for different types (Dog, Bird) using distinct interfaces (DogOption, BirdOption) that both satisfy a common Option interface.

```go
// config holds options for all animals.
type config struct {
	Weight      float64
	Color       string
	MaxAltitude float64
}

// DogOption apply Dog specific options.
type DogOption interface {
	applyDog(config) config
}

// BirdOption apply Bird specific options.
type BirdOption interface {
	applyBird(config) config
}

// Option apply options for all animals.
type Option interface {
	BirdOption
	DogOption
}

type weightOption float64

func (o weightOption) applyDog(c config) config {
	c.Weight = float64(o)
	return c
}

func (o weightOption) applyBird(c config) config {
	c.Weight = float64(o)
	return c
}

func WithWeight(w float64) Option { return weightOption(w) }

type furColorOption string

func (o furColorOption) applyDog(c config) config {
	c.Color = string(o)
	return c
}

func WithFurColor(c string) DogOption { return furColorOption(c) }

type maxAltitudeOption float64

func (o maxAltitudeOption) applyBird(c config) config {
	c.MaxAltitude = float64(o)
	return c
}

func WithMaxAltitude(a float64) BirdOption { return maxAltitudeOption(a) }

func NewDog(name string, o ...DogOption) Dog    {…}
func NewBird(name string, o ...BirdOption) Bird {…}
```

--------------------------------

### Run Integration and Unit Tests (Bash)

Source: https://context7.com/cloudfoundry/bosh-docker-cpi-release/llms.txt

Commands to execute integration and unit tests for the BOSH Docker CPI release using bash scripts or Go's testing framework.

```bash
# Run integration tests
cd tests && ./run.sh

# Run unit tests
./src/bosh-docker-cpi/bin/test

# Run Go tests directly
cd src/bosh-docker-cpi
go test ./...
```

--------------------------------

### Display source file path

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/maxbrunsfeld/counterfeiter/v6/README.md

Displays the path to the Go file containing the interface.

```shell
$ cat path/to/foo/file.go
```

--------------------------------

### Create Root Logger

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/go-logr/logr/README.md

Initialize the root logger in an application's main function. This sets up the chosen logging implementation with initial parameters.

```go
func main() {
    // ... other setup code ...

    // Create the "root" logger.  We have chosen the "logimpl" implementation,
    // which takes some initial parameters and returns a logr.Logger.
    logger := logimpl.New(param1, param2)

    // ... other setup code ...
}
```

--------------------------------

### System Call Entry Points (Assembly)

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/golang.org/x/sys/unix/README.md

These are the entry points for system call dispatch in the hand-written assembly file. They differ in the number of arguments passed to the kernel.

```go
func Syscall(trap, a1, a2, a3 uintptr) (r1, r2, err uintptr)
  func Syscall6(trap, a1, a2, a3, a4, a5, a6 uintptr) (r1, r2, err uintptr)
  func RawSyscall(trap, a1, a2, a3 uintptr) (r1, r2, err uintptr)
```

--------------------------------

### xxhash Benchmarking Commands

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/cespare/xxhash/v2/README.md

Commands to run benchmarks for the pure Go and assembly implementations of the `Sum64` function. Requires `benchstat`.

```bash
benchstat <(go test -tags purego -benchtime 500ms -count 15 -bench 'Sum64$')
benchstat <(go test -benchtime 500ms -count 15 -bench 'Sum64$')
```

--------------------------------

### Initialize Instrumentation with Error Handling

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/go.opentelemetry.io/otel/CONTRIBUTING.md

Properly initialize instrumentation, returning any errors to the caller. Handles cases where observability is disabled.

```go
func newInstrumentation() (*instrumentation, error) {
    if !x.Observability.Enabled() {
        return nil, nil
    }
 
    m := otel.GetMeterProvider().Meter(/* initialize meter */)
    counter, err := otelconv.NewSDKComponentCounter(m)
	// Use the partially initialized counter if available.
	i := &instrumentation{counter: counter}
	// Return any error to the caller.
    return i, err
}
```

--------------------------------

### Create Persistent Disk (Go)

Source: https://context7.com/cloudfoundry/bosh-docker-cpi-release/llms.txt

Creates a persistent disk by provisioning a Docker volume. It can optionally be co-located with a specific VM.

```go
func (a CreateDiskMethod) CreateDisk(
    size int,
    cloudProps apiv1.DiskCloudProps,
    vmCID *apiv1.VMCID,
) (apiv1.DiskCID, error)
```

--------------------------------

### Run go generate

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/maxbrunsfeld/counterfeiter/v6/README.md

Execute the generation process for the current directory or the entire module.

```shell
$ go generate ./...
```

--------------------------------

### Attach Disk to VM (Go)

Source: https://context7.com/cloudfoundry/bosh-docker-cpi-release/llms.txt

Attaches a persistent disk to a VM by mounting the Docker volume into the container. Returns a disk hint for the BOSH agent.

```go
func (a AttachDiskMethod) AttachDiskV2(
    vmCID apiv1.VMCID,
    diskCID apiv1.DiskCID,
) (apiv1.DiskHint, error)
```

--------------------------------

### Activate Observability via Environment Variable

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/go.opentelemetry.io/otel/CONTRIBUTING.md

Check the OTEL_GO_X_OBSERVABILITY environment variable to conditionally enable experimental observability features.

```go
import "go.opentelemetry.io/otel/*/internal/x"

if x.Observability.Enabled() {
    // Initialize observability metrics
}
```

--------------------------------

### Instantiate test double

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/maxbrunsfeld/counterfeiter/v6/README.md

Import the generated package and instantiate the fake object.

```go
import "my-repo/path/to/foo/foofakes"

var fake = &foofakes.FakeMySpecialInterface{}
```

--------------------------------

### Import Hash Implementations

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/opencontainers/go-digest/README.md

Ensure necessary hash implementations (e.g., SHA-256, SHA-512) are imported into your application to prevent panics. This allows for flexibility in choosing hash algorithms.

```go
import (
    _ "crypto/sha256"
    _ "crypto/sha512"
)
```

--------------------------------

### Check Version Against Constraints

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/Masterminds/semver/v3/README.md

Parses a constraint string and a version string, then evaluates if the version satisfies the constraint.

```go
c, err := semver.NewConstraint(">= 1.2.3")
if err != nil {
    // Handle constraint not being parsable.
}

v, err := semver.NewVersion("1.3")
if err != nil {
    // Handle version not being parsable.
}
// Check if the version meets the constraints. The variable a will be true.
a := c.Check(v)
```

--------------------------------

### Abstracting the os package

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/bmatcuk/doublestar/README.md

Information on using `GlobOS` and `PathMatchOS` for custom filesystem implementations.

```APIDOC
### Abstracting the `os` package

**doublestar** by default uses the `Open`, `Stat`, and `Lstat`, functions and `PathSeparator` value from the standard library's `os` package. To abstract this, for example to be able to perform tests of Windows paths on Linux, or to interoperate with your own filesystem code, it includes the functions `GlobOS` and `PathMatchOS` which are identical to `Glob` and `PathMatch` except that they operate on an `OS` interface:

```go
type OS interface {
    Lstat(name string) (os.FileInfo, error)
    Open(name string) (*os.File, error)
    PathSeparator() rune
    Stat(name string) (os.FileInfo, error)
}
```

`StandardOS` is a value that implements this interface by calling functions in the standard library's `os` package.
```

--------------------------------

### Run Pre-release Make Target

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/go.opentelemetry.io/otel/RELEASING.md

Creates a release branch for the specified module set.

```bash
make prerelease MODSET=<module set>
```

--------------------------------

### Run Unit Tests

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/README.md

Execute the provided test script located in the src/github.com/cppforlife/bosh-docker-cpi/bin/ directory to run unit tests.

```bash
./src/github.com/cppforlife/bosh-docker-cpi/bin/test
```

--------------------------------

### Run Integration Tests

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/README.md

Navigate to the tests directory and execute the run.sh script to perform integration tests for the BOSH Docker CPI release.

```bash
cd tests && ./run.sh
```

--------------------------------

### Create Docker overlay networks

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/docs/snippets.md

Commands to create Docker overlay networks with specific subnets.

```bash
$ docker network create -d overlay --subnet=10.10.0.2/16 net2
$ docker network create -d overlay --subnet=172.16.0.0/16 net2
```

--------------------------------

### Glob Filesystem

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/bmatcuk/doublestar/README.md

Use Glob to find all files and directories matching a pattern. The pattern can be relative or absolute. This is a drop-in replacement for filepath.Glob.

```go
func Glob(pattern string) ([]string, error)
```

--------------------------------

### Run project tests

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/maxbrunsfeld/counterfeiter/v6/README.md

Execute the CI script to run tests for the counterfeiter project.

```shell
$ scripts/ci.sh
```

--------------------------------

### Sign Release Artifacts

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/go.opentelemetry.io/otel/RELEASING.md

Sets environment variables and signs the release archives using a GPG key.

```terminal
export VERSION="<version>"  # e.g., v1.32.0
export KEY_ID="<your-gpg-key-id>"

gpg --local-user $KEY_ID --armor --detach-sign opentelemetry-go-$VERSION.tar.gz
gpg --local-user $KEY_ID --armor --detach-sign opentelemetry-go-$VERSION.zip
```

--------------------------------

### Light Stemcell Creation

Source: https://context7.com/cloudfoundry/bosh-docker-cpi-release/llms.txt

Instructions and script for creating lightweight stemcells from Docker images.

```APIDOC
## Creating Light Stemcells

### Description
Use the provided script to create lightweight stemcells from Docker images that can be uploaded to BOSH.

### Usage
```bash
./dev/create-light-stemcell.sh <docker-image-reference> [output-file]
```

### Example
```bash
./dev/create-light-stemcell.sh ghcr.io/cloudfoundry/ubuntu-noble-stemcell:1.165 my-stemcell.tgz
```

### Process
The script will:
1. Extract OS name from image (e.g., `ubuntu-noble-stemcell` -> `ubuntu-noble`).
2. Pull the image if Docker is available and extract SHA256 digest.
3. Create `stemcell.MF` metadata file.
4. Package into a BOSH-compatible tarball.

### Upload to BOSH Director
```bash
bosh upload-stemcell my-stemcell.tgz
```

### View Uploaded Stemcell
```bash
bosh stemcells
```

### Output Example
```
NAME                      VERSION  OS            CID
bosh-docker-ubuntu-noble  1.165    ubuntu-noble  ghcr.io/cloudfoundry/ubuntu-noble-stemcell@sha256:d4ca21...
```
```

--------------------------------

### Running Tests

Source: https://context7.com/cloudfoundry/bosh-docker-cpi-release/llms.txt

Commands for executing integration and unit tests for the Docker CPI.

```APIDOC
## Running Tests

### Description
Commands to run integration and unit tests for the Docker CPI.

### Integration Tests
```bash
cd tests && ./run.sh
```

### Unit Tests
```bash
./src/bosh-docker-cpi/bin/test
```

### Go Tests
```bash
cd src/bosh-docker-cpi
go test ./...
```
```

--------------------------------

### Unmarshal and Marshal YAML data

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/go.yaml.in/yaml/v3/README.md

Demonstrates how to parse YAML into a Go struct or a map, and how to serialize them back into YAML format.

```go
package main

import (
	"fmt"
	"log"

	"go.yaml.in/yaml/v3"
)

var data = `
a: Easy!
b:
  c: 2
  d: [3, 4]
`

// Note: struct fields must be public in order for unmarshal to
// correctly populate the data.
type T struct {
	A string
	B struct {
		RenamedC int   `yaml:"c"`
		D	[]int `yaml:",flow"`
	}
}

func main() {
	t := T{}

	err := yaml.Unmarshal([]byte(data), &t)
	if err != nil {
		log.Fatalf("error: %v", err)
	}
	fmt.Printf("--- t:\n%v\n\n", t)

	d, err := yaml.Marshal(&t)
	if err != nil {
		log.Fatalf("error: %v", err)
	}
	fmt.Printf("--- t dump:\n%s\n\n", string(d))

	m := make(map[interface{}]interface{})

	err = yaml.Unmarshal([]byte(data), &m)
	if err != nil {
		log.Fatalf("error: %v", err)
	}
	fmt.Printf("--- m:\n%v\n\n", m)

	d, err = yaml.Marshal(&m)
	if err != nil {
		log.Fatalf("error: %v", err)
	}
	fmt.Printf("--- m dump:\n%s\n\n", string(d))
}
```

--------------------------------

### Implement CreateStemcell Method

Source: https://context7.com/cloudfoundry/bosh-docker-cpi-release/llms.txt

Imports a stemcell image into Docker, supporting both traditional tar archives and light stemcells.

```go
// Function signature
func (a CreateStemcellMethod) CreateStemcell(
    imagePath string,
    cloudProps apiv1.StemcellCloudProps,
) (apiv1.StemcellCID, error)

// Light stemcell metadata format (stemcell.MF)
// ---
// name: bosh-docker-ubuntu-noble
// version: "1.165"
// api_version: 3
// operating_system: ubuntu-noble
// stemcell_formats:
// - docker-light
// cloud_properties:
//   image_reference: "ghcr.io/cloudfoundry/ubuntu-noble-stemcell:1.165"
//   digest: "sha256:d4ca21a75f1ff6be382695e299257f054585143bf09762647bcb32f37be5eaf3"

// Returns stemcell CID (for light stemcells, this is the image digest reference)
// Example: ghcr.io/cloudfoundry/ubuntu-noble-stemcell@sha256:d4ca21a75f1ff...
```

--------------------------------

### Add Counterfeiter as a tool dependency

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/maxbrunsfeld/counterfeiter/v6/README.md

Establish a tool dependency on counterfeiter within a Go module.

```shell
go get -tool github.com/maxbrunsfeld/counterfeiter/v6
```

--------------------------------

### Info Method

Source: https://context7.com/cloudfoundry/bosh-docker-cpi-release/llms.txt

Returns CPI capabilities and supported stemcell formats to the BOSH Director.

```APIDOC
## Info Method

Returns CPI capabilities and supported stemcell formats to the BOSH Director.

### Response Example (200 OK)
```json
{
  "stemcell_formats": ["warden-tar", "general-tar", "docker-light"],
  "api_version": 2
}
```
```

--------------------------------

### Manage Attribute and Option Allocation with sync.Pool

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/go.opentelemetry.io/otel/CONTRIBUTING.md

This Go code demonstrates using sync.Pool to manage attribute slices and options, minimizing allocations in measurement calls with dynamic attributes. Pools are most effective with many objects of the same size that are repeatedly used.

```go
var (
	attrPool = sync.Pool{
        New: func() any {
		    // Pre-allocate common capacity
    		knownCap := 8 // Adjust based on expected usage
            s := make([]attribute.KeyValue, 0, knownCap)
    	    // Return a pointer to avoid extra allocation on Put().
            return &s
        },
    }

	addOptPool = &sync.Pool{
		New: func() any {
			const n = 1 // WithAttributeSet
			o := make([]metric.AddOption, 0, n)
    		// Return a pointer to avoid extra allocation on Put().
			return &o
		},
	}
)

func (i *instrumentation) record(ctx context.Context, value int64, baseAttrs ...attribute.KeyValue) {
    attrs := attrPool.Get().(*[]attribute.KeyValue)
    defer func() {
        *attrs = (*attrs)[:0] // Reset.
        attrPool.Put(attrs)
    }()

    *attrs = append(*attrs, baseAttrs...)
    // Add any dynamic attributes.
    *attrs = append(*attrs, semconv.OTelComponentName("exporter-1"))

	addOpt := addOptPool.Get().(*[]metric.AddOption)
	defer func() {
		*addOpt = (*addOpt)[:0]
		addOptPool.Put(addOpt)
	}()

	set := attribute.NewSet(*attrs...)
	*addOpt = append(*addOpt, metric.WithAttributeSet(set))

    i.counter.Add(ctx, value, *addOpt...)
}
```

--------------------------------

### Unmarshal and Marshal YAML data in Go

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/gopkg.in/yaml.v3/README.md

Demonstrates how to unmarshal YAML into a struct or a map, and how to marshal data back into YAML format. Struct fields must be exported for the unmarshaler to populate them.

```Go
package main

import (
        "fmt"
        "log"

        "gopkg.in/yaml.v3"
)

var data = `
a: Easy!
b:
  c: 2
  d: [3, 4]
`

// Note: struct fields must be public in order for unmarshal to
// correctly populate the data.
type T struct {
        A string
        B struct {
                RenamedC int   `yaml:"c"`
                D        []int `yaml:",flow"`
        }
}

func main() {
        t := T{}
    
        err := yaml.Unmarshal([]byte(data), &t)
        if err != nil {
                log.Fatalf("error: %v", err)
        }
        fmt.Printf("--- t:\n%v\n\n", t)
    
        d, err := yaml.Marshal(&t)
        if err != nil {
                log.Fatalf("error: %v", err)
        }
        fmt.Printf("--- t dump:\n%s\n\n", string(d))
    
        m := make(map[interface{}]interface{})
    
        err = yaml.Unmarshal([]byte(data), &m)
        if err != nil {
                log.Fatalf("error: %v", err)
        }
        fmt.Printf("--- m:\n%v\n\n", m)
    
        d, err = yaml.Marshal(&m)
        if err != nil {
                log.Fatalf("error: %v", err)
        }
        fmt.Printf("--- m dump:\n%s\n\n", string(d))
}
```

--------------------------------

### Verify Release Changes

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/go.opentelemetry.io/otel/RELEASING.md

Displays the differences in the pre-release branch to verify version updates.

```bash
git diff ...prerelease_<module set>_<new tag>
```

--------------------------------

### Performance benchmark results

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/felixge/httpsnoop/README.md

Benchmark output comparing a baseline handler to one using CaptureMetrics, showing negligible overhead.

```text
BenchmarkBaseline-8      	   20000	     94912 ns/op
BenchmarkCaptureMetrics-8	   20000	     95461 ns/op
```

--------------------------------

### Clone opentelemetry-go Repository

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/go.opentelemetry.io/otel/CONTRIBUTING.md

Use this command to clone the opentelemetry-go repository to your local machine.

```sh
git clone https://github.com/open-telemetry/opentelemetry-go.git
```

--------------------------------

### Run Gomega tests and linters

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/onsi/gomega/CONTRIBUTING.md

Commands to verify code quality and test coverage before submitting a pull request.

```bash
ginkgo -r -p
```

```bash
go vet ./...
```

--------------------------------

### Create Light Stemcell Script

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/README.md

Use this bash script to create a light stemcell from any Docker image. It extracts OS information, generates metadata, and creates a tarball for BOSH Director.

```bash
./dev/create-light-stemcell.sh <docker-image-reference> <output-file>
```

```bash
./dev/create-light-stemcell.sh ghcr.io/cloudfoundry/ubuntu-noble-stemcell:1.165 my-stemcell.tgz
```

--------------------------------

### Call Template Functions

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/go-task/slim-sprig/v3/README.md

Use Slim-Sprig functions within Go templates using the pipe syntax.

```text
{{ "hello!" | upper | repeat 5 }}
```

```text
HELLO!HELLO!HELLO!HELLO!HELLO!
```

--------------------------------

### Run go generate

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/github.com/Microsoft/go-winio/README.md

Execute go generate for the entire repository to update auto-generated code. This command ensures all generated files are up-to-date.

```shell
> go generate ./...
```

--------------------------------

### Check VM Existence (Go)

Source: https://context7.com/cloudfoundry/bosh-docker-cpi-release/llms.txt

Use this function to determine if a virtual machine (container) already exists.

```go
func (a HasVMMethod) HasVM(cid apiv1.VMCID) (bool, error)
```

--------------------------------

### Import BOSH stemcell image

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/docs/snippets.md

Command to decompress and import a BOSH stemcell image into Docker.

```bash
$ gunzip -d < ~/Downloads/bosh-stemcell-3147-warden-boshlite-ubuntu-trusty-go_agent/image | docker import - bosh-stemcell2
```

--------------------------------

### Clone opentelemetry-go with Git

Source: https://github.com/cloudfoundry/bosh-docker-cpi-release/blob/master/src/bosh-docker-cpi/vendor/go.opentelemetry.io/otel/CONTRIBUTING.md

Alternatively, clone the opentelemetry-go repository directly using Git. Note that 'git clone' does not use the 'go.opentelemetry.io/otel' redirector.

```sh
git clone https://github.com/open-telemetry/opentelemetry-go
```

--------------------------------

### Run BOSH Docker CPI tests

Source: https://context7.com/cloudfoundry/bosh-docker-cpi-release/llms.txt

Execute unit tests for the CPI, stemcell, and VM packages within the project.

```bash
go test ./cpi/...
go test ./stemcell/...
go test ./vm/...
```

--------------------------------

### Create Light Stemcell Script

Source: https://context7.com/cloudfoundry/bosh-docker-cpi-release/llms.txt

Use this bash script to create lightweight stemcells from Docker images. It pulls the image, extracts metadata, and packages it into a BOSH-compatible tarball.

```bash
# Usage
./dev/create-light-stemcell.sh <docker-image-reference> [output-file]

# Example: Create a light stemcell from a GitHub Container Registry image
./dev/create-light-stemcell.sh ghcr.io/cloudfoundry/ubuntu-noble-stemcell:1.165 my-stemcell.tgz

# The script will:
# 1. Extract OS name from image (ubuntu-noble-stemcell -> ubuntu-noble)
# 2. Pull the image if Docker is available and extract SHA256 digest
# 3. Create stemcell.MF metadata file
# 4. Package into BOSH-compatible tarball
```

```bash
# Upload to BOSH Director
bosh upload-stemcell my-stemcell.tgz

# View uploaded stemcell with digest-based CID
bosh stemcells
# NAME                      VERSION  OS            CID
# bosh-docker-ubuntu-noble  1.165    ubuntu-noble  ghcr.io/cloudfoundry/ubuntu-noble-stemcell@sha256:d4ca21...
```