### Install Go YAML Package

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

Use 'go get' to install the v3 of the YAML package for Go.

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

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

### Preview documentation

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

Starts a local Jekyll server to preview documentation changes.

```bash
bundle exec jekyll serve
```

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

### Install UUID package

Source: https://github.com/cloudfoundry/bosh-openstack-cpi-release/blob/master/src/openstack_cpi_golang/vendor/github.com/google/uuid/README.md

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

```sh
go get github.com/google/uuid
```

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

### Install Counterfeiter

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

Install the tool to your GOPATH to enable shell invocation outside of modules.

```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> [-]
```

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

### Migrate format strings to structured logging

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

Examples of converting 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)
```

```go
log.Printf("unable to reflect over type %T")
```

```go
logger.Info("unable to reflect over type", "type", fmt.Sprintf("%T"))
```

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

### Create Root Logger

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

Initialize the root logger early in your application's lifecycle. This example uses a hypothetical 'logimpl' implementation.

```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 ...
}
```

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

### Define Interface

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

Example interface definition for generating a test double.

```go
package foo

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

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

### BOSH Deployment Manifest Configuration

Source: https://github.com/cloudfoundry/bosh-openstack-cpi-release/blob/master/src/bosh_openstack_cpi/docs/cpi_config.md

Example configuration for a full BOSH deployment manifest, detailing OpenStack and registry properties.

```yaml
---
name: my-bosh

...

properties:
  openstack:
    auth_url: http://0.0.0.0:5000/v3.0
    username: openstack-user
    api_key: openstack-password
    tenant: dev
    domain: domain1
    region: west-coast
    endpoint_type: publicURL
    state_timeout: 300
    boot_from_volume: false
    stemcell_public_visibility: false
    connection_options: {}
    default_key_name: 
    default_security_groups: 
    wait_resource_poll_interval: 5 
    config_drive: disk 
  registry: 
    address: 0.0.0.0
    http:
      port: 25777
      user: registry-user
      password: registry-password
  agent: {} # optional agent config


```

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

### microBOSH Deployment Manifest Configuration

Source: https://github.com/cloudfoundry/bosh-openstack-cpi-release/blob/master/src/bosh_openstack_cpi/docs/cpi_config.md

Example configuration for the microBOSH deployment manifest, specifying OpenStack and registry properties.

```yaml
---
name: my-micro

...

cloud:
  plugin: openstack
  properties:
    openstack:
      auth_url: http://0.0.0.0:5000/v2.0
      username: openstack-user
      api_key: openstack-password
      tenant: dev
      region: west-coast
      endpoint_type: publicURL
      state_timeout: 300
      boot_from_volume: false
      stemcell_public_visibility: false
      connection_options: {}
      default_key_name: 
      default_security_groups: 
      wait_resource_poll_interval: 5 
      config_drive: disk 
    registry:
      endpoint: http://0.0.0.0:25777
      user: registry-user
      password: registry-password
    agent: {} # optional agent config


```

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

### Define a Ginkgo Spec Suite

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

Uses Describe, Context, and It blocks to structure test scenarios with setup and teardown logic via BeforeEach.

```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))
    })
})
```

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

### OpenStack Nova API - Get Server

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

Retrieves details for a specific virtual machine server. Requires tenant ID and server ID.

```bash
GET /v2.1/<tenant_id>/servers/<server_id>
```

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

### Get Volume by ID

Source: https://github.com/cloudfoundry/bosh-openstack-cpi-release/blob/master/ci/ruby_scripts/spec/assets/expected_api_calls.md

Retrieve details of a specific volume using its unique identifier.

```bash
GET /v2/<tenant_id>/volumes/<resource_id>
```

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

### OpenStack Glance API - Get Image

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

Retrieves details for a specific image. Requires the image ID.

```bash
GET /v2/images/<image_id>
```

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

### Get Ports by IP Address and Network

Source: https://github.com/cloudfoundry/bosh-openstack-cpi-release/blob/master/ci/ruby_scripts/spec/assets/expected_api_calls.md

Fetch network ports filtered by IP address and network ID.

```bash
GET /v2/ports?fixed_ips=["ip_address=<ip_address>", {"network_id":"<network_id>"}]
```

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

### Provision a Server

Source: https://github.com/cloudfoundry/bosh-openstack-cpi-release/blob/master/src/openstack_cpi_golang/vendor/github.com/gophercloud/gophercloud/README.md

Use the Compute service client's Create method to provision a new server. Specify the desired flavor and image IDs. The result is a server object containing details of the newly created resource.

```go
import "github.com/gophercloud/gophercloud/openstack/compute/v2/servers"

server, err := servers.Create(client, servers.CreateOpts{
	Name:      "My new server!",
	FlavorRef: "flavor_id",
	ImageRef:  "image_id",
}).Extract()
```

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

### Create Volume

Source: https://github.com/cloudfoundry/bosh-openstack-cpi-release/blob/master/ci/ruby_scripts/spec/assets/expected_api_calls.md

Create a new volume with a specified name, description, and size.

```bash
POST /v2/<tenant_id>/volumes body: {"volume":{"name":"<name>","description":"<description>","size":"<size>"}}
```

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

### OpenStack Neutron API - Get Network

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

Retrieves details for a specific network. Requires the network ID.

```bash
GET /v2.0/networks/<network_id>
```

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

### Instantiate Fake

Source: https://github.com/cloudfoundry/bosh-openstack-cpi-release/blob/master/src/openstack_cpi_golang/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{}
```

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

### POST /v2.1/<tenant_id>/servers

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

Creates a new server instance in Nova.

```APIDOC
## POST /v2.1/<tenant_id>/servers

### Description
Creates a new server instance.

### Path Parameters
- **tenant_id** (string) - Required - The ID of the project/tenant.

### Request Body
- **server** (object) - Required - Contains flavorRef, name, imageRef, and network configuration.
```

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

### View Source File

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

Display the contents of the source file containing the interface.

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

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

### Create VM

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

Provisions a new server with specific cloud properties and network configurations. Supports manual, VIP, and dynamic network types.

```ruby
# CPI method signature
def create_vm(agent_id, stemcell_id, cloud_properties, network_spec, disk_locality, environment)

# Example cloud_properties
cloud_properties = {
  'instance_type' => 'm1.large',
  'availability_zone' => 'nova',
  'scheduler_hints' => {
    'group' => 'server-group-uuid'
  },
  'loadbalancer_pools' => [
    { 'name' => 'web-pool', 'port' => 80 },
    { 'name' => 'api-pool', 'port' => 8080 }
  ],
  'allowed_address_pairs' => '10.0.0.100',
  'root_disk' => {
    'size' => 20
  },
  'boot_from_volume' => true
}

# Example network_spec with manual and vip networks
network_spec = {
  'default' => {
    'type' => 'manual',
    'ip' => '10.0.0.10',
    'netmask' => '255.255.255.0',
    'gateway' => '10.0.0.1',
    'dns' => ['8.8.8.8'],
    'default' => ['gateway', 'dns'],
    'cloud_properties' => {
      'net_id' => 'network-uuid',
      'security_groups' => ['bosh-sg', 'cf-sg']
    }
  },
  'vip' => {
    'type' => 'vip',
    'ip' => '203.0.113.10',
    'cloud_properties' => {}
  }
}

# Example with dynamic network
network_spec = {
  'default' => {
    'type' => 'dynamic',
    'cloud_properties' => {
      'net_id' => 'network-uuid',
      'security_groups' => ['bosh-sg']
    }
  }
}
```

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

### Import Gophercloud Package

Source: https://github.com/cloudfoundry/bosh-openstack-cpi-release/blob/master/src/openstack_cpi_golang/vendor/github.com/gophercloud/gophercloud/README.md

Reference the Gophercloud package in your Go code.

```go
import "github.com/gophercloud/gophercloud"
```

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

### OpenStack LBaaS v2 API - Get Pool by ID

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

Retrieves a load balancer pool by its ID. Requires the pool ID.

```bash
GET /v2.0/lbaas/pools/<pool_id>
```

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

### Authenticate with ClientConfig

Source: https://github.com/cloudfoundry/bosh-openstack-cpi-release/blob/master/src/openstack_cpi_golang/vendor/github.com/gophercloud/gophercloud/README.md

Generate an authenticated client provider using the `clientconfig` package from `gophercloud/utils`. This method simplifies authentication and supports reading `clouds.yaml` files. You can also set the `OS_CLOUD` environment variable.

```go
import (
	"github.com/gophercloud/utils/openstack/clientconfig"
)

// You can also skip configuring this and instead set 'OS_CLOUD' in your
// environment
opts := new(clientconfig.ClientOpts)
opts.Cloud = "devstack-admin"

provider, err := clientconfig.AuthenticatedClient(opts)
```

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

### OpenStack LBaaS v2 API - Get Pool by Name

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

Retrieves a load balancer pool by its name. Requires the pool name.

```bash
# LBaaS v2 (Load Balancer)
GET /v2.0/lbaas/pools?name=<pool_name>
```

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

### OpenStack Neutron API - Get Floating IP by Address

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

Retrieves details for a floating IP address. Requires the floating IP address.

```bash
GET /v2.0/floatingips?floating_ip_address=<ip>
```

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

### Create Server Metadata

Source: https://github.com/cloudfoundry/bosh-openstack-cpi-release/blob/master/ci/ruby_scripts/spec/assets/expected_api_calls.md

Use this endpoint to add or update metadata for a specific server instance.

```bash
POST /v2.1/<tenant_id>/servers/<resource_id>/metadata body: {"metadata":"<metadata>"}
```

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

### OpenStack Cinder API - Get Volume

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

Retrieves details for a specific persistent disk volume. Requires tenant ID and volume ID.

```bash
GET /v2/<tenant_id>/volumes/<volume_id>
```

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

### OpenStack Nova API - Create Server

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

Creates a new virtual machine server in OpenStack. Requires tenant ID and a JSON body specifying server details like flavor, name, image, and network.

```bash
# Nova (Compute) - Server Operations
POST /v2.1/<tenant_id>/servers
# Body: {"server":{"flavorRef":"flavor-id","name":"vm-name","imageRef":"image-id","availability_zone":"nova","user_data":"base64-data","key_name":"keypair","security_groups":[{"name":"sg"}],"networks":[{"uuid":"net-id"}]}}
```

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

### OpenStack LBaaS v2 API - Get Load Balancer by ID

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

Retrieves details for a specific load balancer. Requires the load balancer ID.

```bash
GET /v2.0/lbaas/loadbalancers/<lb_id>
```

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

### OpenStack Nova API - List Flavors

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

Retrieves a detailed list of available instance flavors. Requires tenant ID.

```bash
GET /v2.1/<tenant_id>/flavors/detail
```

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

### Get CPI Info

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

Retrieves information about the CPI's capabilities, including supported stemcell formats. Returns a hash containing API version and stemcell formats.

```ruby
# CPI method signature
def info

# Returns: Hash with CPI information
# {
#   'api_version' => 2,
#   'stemcell_formats' => ['openstack-raw', 'openstack-qcow2', 'openstack-light']
# }
```
```

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

### Commit and Release

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

Commands to commit the version change, push to the repository, and create a GitHub release.

```bash
git commit -m "vM.m.p"
git push
gh release create "vM.m.p"
git fetch --tags origin master
```

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

### Create Development Release

Source: https://github.com/cloudfoundry/bosh-openstack-cpi-release/blob/master/CONTRIBUTING.md

Generate a BOSH release with a tarball for manual testing and deployment purposes.

```bash
$ bosh create release --force --with-tarball
```

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

### Create Compute Service Client with ClientConfig

Source: https://github.com/cloudfoundry/bosh-openstack-cpi-release/blob/master/src/openstack_cpi_golang/vendor/github.com/gophercloud/gophercloud/README.md

Create a Compute service client by injecting the authenticated provider. This client is used to interact with the OpenStack Compute API.

```go
client, err := clientconfig.NewServiceClient("compute", opts)
```

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

### Authenticate with Explicit Credentials

Source: https://github.com/cloudfoundry/bosh-openstack-cpi-release/blob/master/src/openstack_cpi_golang/vendor/github.com/gophercloud/gophercloud/README.md

Manually provide authentication options, including the Identity endpoint, username, and password, to create an authenticated client provider. This method does not use `clouds.yaml`.

```go
import (
	"github.com/gophercloud/gophercloud"
	"github.com/gophercloud/gophercloud/openstack"
)

// Option 1: Pass in the values yourself
opts := gophercloud.AuthOptions{
  IdentityEndpoint: "https://openstack.example.com:5000/v2.0",
  Username: "{username}",
  Password: "{password}",
}
```

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

### OpenStack Nova API - Add Server Metadata

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

Adds metadata to a virtual machine server. Requires tenant ID, server ID, and a JSON body with metadata key-value pairs.

```bash
POST /v2.1/<tenant_id>/servers/<server_id>/metadata
# Body: {"metadata":{"key":"value"}}
```

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

### Authenticate with Environment Variables

Source: https://github.com/cloudfoundry/bosh-openstack-cpi-release/blob/master/src/openstack_cpi_golang/vendor/github.com/gophercloud/gophercloud/README.md

Use the `openstack.AuthOptionsFromEnv()` utility function to retrieve authentication options from environment variables. This is a convenient way to configure credentials without hardcoding them.

```go
import (
	"github.com/gophercloud/gophercloud"
	"github.com/gophercloud/gophercloud/openstack"
)

// Option 2: Use a utility function to retrieve all your environment variables
opts, err := openstack.AuthOptionsFromEnv()
```

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

### Run go generate Command

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

Execute the `go generate ./...` command from your module's root directory to process all `go:generate` directives and create fake implementations for your interfaces. This ensures all necessary test doubles are up-to-date.

```shell
go generate ./...

```

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

### Create Image

Source: https://github.com/cloudfoundry/bosh-openstack-cpi-release/blob/master/ci/ruby_scripts/spec/assets/expected_api_calls.md

This endpoint is used to create a new private image with specified properties like name, disk format, and OS type.

```bash
POST /v2/images body: {"name":"<name>","disk_format":"qcow2","container_format":"bare","visibility":"private","version":"<version>","os_type":"linux","os_distro":"ubuntu","architecture":"x86_64","auto_disk_config":"true","hypervisor_type":"kvm"}
```

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

### Track Tool Dependencies with tools.go

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

Use a `tools.go` file to track tool dependencies for a module, ensuring consistent tool versions across your project. This is essential for reproducible builds and testing.

```go
//go:build tools

package tools

import (
	_ "github.com/maxbrunsfeld/counterfeiter/v6"
)

// This file imports packages that are used when running go generate, or used
// during the development process but not otherwise depended on by built code.

```

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

### OpenStack Cinder API - Create Snapshot

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

Creates a snapshot of a persistent disk volume. Requires tenant ID and a JSON body specifying the volume ID, snapshot name, and description.

```bash
POST /v2/<tenant_id>/snapshots
# Body: {"snapshot":{"volume_id":"vol-id","name":"snap-name","description":"desc","force":true}}
```

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

### Stub Return Values

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

Configure the fake to return specific values when called.

```go
fake.DoThingsReturns(3, errors.New("the-error"))

num, err := fake.DoThings("stuff", 5)
Expect(num).To(Equal(3))
Expect(err).To(Equal(errors.New("the-error")))
```

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

### Unmarshal and Marshal YAML Data in Go

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

Demonstrates unmarshalling YAML data into a Go struct and a map, and then marshalling them back into YAML format. Ensure struct fields are public for correct unmarshalling.

```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))
}
```

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

### Create Disk in OpenStack

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

Creates a new OpenStack volume with a specified size and optional properties like volume type. Can optionally be placed in the same availability zone as a target server for data locality.

```ruby
# CPI method signature
def create_disk(size, cloud_properties, server_id = nil)

# Example cloud_properties
cloud_properties = {
  'type' => 'SSD'  # Volume type name in OpenStack
}

# Create a 10GB disk
size = 10240  # Size in MiB (minimum 1024 MiB = 1 GiB)

# Optional: Create in same AZ as server for locality
server_id = "server-uuid"

# Returns: OpenStack volume UUID
# "volume-a1b2c3d4-e5f6-7890-abcd-ef1234567890"
```

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

### Load Slim-Sprig FuncMap in Go

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

Load the Slim-Sprig FuncMap before parsing templates. Ensure the FuncMap is set prior to loading template files.

```go
import (
  "html/template"

  "github.com/go-task/slim-sprig"
)

// This example illustrates that the FuncMap *must* be set before the
// templates themselves are loaded.
tpl := template.Must(
  template.New("base").Funcs(sprig.FuncMap()).ParseGlob("*.html")
)
```

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

### Snapshot Disk in OpenStack

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

Creates a snapshot of an OpenStack volume with metadata tags for identification. Use for backup or creating new volumes from existing data.

```ruby
# CPI method signature
def snapshot_disk(disk_id, metadata)

# Example metadata
metadata = {
  'deployment' => 'cf',
  'job' => 'api',
  'index' => '0',
  'instance_id' => 'instance-uuid',
  'director_name' => 'my-bosh'
}

disk_id = "volume-a1b2c3d4-e5f6-7890-abcd-ef1234567890"

# Creates snapshot with metadata tags
# Returns: OpenStack snapshot UUID
# "snapshot-a1b2c3d4-e5f6-7890-abcd-ef1234567890"
```

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

### Invoke Counterfeiter from Shell

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

Use the `go run` command to invoke Counterfeiter directly from the shell, providing options for output path, fake name, header files, and the source path and interface name.

```shell
go run github.com/maxbrunsfeld/counterfeiter/v6

```

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

### create_vm

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

Creates a new OpenStack server (VM) using the specified stemcell, cloud properties, and network configuration.

```APIDOC
## create_vm

### Description
Creates a new OpenStack server (VM) using the specified stemcell, cloud properties, and network configuration. Supports multiple network types, load balancer pool integration, and availability zone placement.

### Parameters
- **agent_id** (string) - Required - Unique identifier for the BOSH agent.
- **stemcell_id** (string) - Required - UUID of the stemcell to use.
- **cloud_properties** (hash) - Required - VM configuration such as instance type and availability zone.
- **network_spec** (hash) - Required - Network configuration including manual, dynamic, or vip networks.
- **disk_locality** (array) - Optional - List of persistent disk IDs.
- **environment** (hash) - Optional - Environment variables for the VM.
```

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

### OpenStack Nova API - List Key Pairs

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

Retrieves a list of available SSH key pairs. Requires tenant ID.

```bash
GET /v2.1/<tenant_id>/os-keypairs
```

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

### OpenStack Nova API - Attach Volume to Server

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

Attaches a persistent disk volume to a virtual machine server. Requires tenant ID, server ID, and a JSON body specifying the volume ID and device.

```bash
POST /v2.1/<tenant_id>/servers/<server_id>/os-volume_attachments
# Body: {"volumeAttachment":{"volumeId":"volume-id","device":"/dev/sdc"}}
```

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

### Define system call entry points in assembly

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

These functions are implemented in asm_${GOOS}_${GOARCH}.s to handle system call dispatching.

```assembly
  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)
```

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

### Verify Fake Calls

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

Use call count and argument retrieval methods to verify interactions.

```go
fake.DoThings("stuff", 5)

Expect(fake.DoThingsCallCount()).To(Equal(1))

str, num := fake.DoThingsArgsForCall(0)
Expect(str).To(Equal("stuff"))
Expect(num).To(Equal(uint64(5)))
```

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

### Run Ginkgo Specs in Parallel

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

Use the '-p' flag with the ginkgo CLI to run your test suite in parallel. This is useful for improving test execution performance.

```bash
ginkgo -p
```

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

### OpenStack Neutron API - List Ports by Device

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

Retrieves a list of network ports associated with a specific device (e.g., a VM). Requires the server ID.

```bash
GET /v2.0/ports?device_id=<server_id>
```

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

### OpenStack Cinder API - Create Volume

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

Creates a new persistent disk volume. Requires tenant ID and a JSON body specifying volume name, size, and availability zone.

```bash
# Cinder (Volume) - Disk Operations
POST /v2/<tenant_id>/volumes
# Body: {"volume":{"name":"volume-name","description":"","size":10,"availability_zone":"nova"}}
```

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

### Calculate VM Cloud Properties

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

Maps generic VM requirements (CPU, RAM, disk) to OpenStack-specific cloud properties by finding a matching flavor. Input is a hash of requirements.

```ruby
# CPI method signature
def calculate_vm_cloud_properties(requirements)

# Example requirements
requirements = {
  'cpu' => 4,
  'ram' => 8192,           # RAM in MiB
  'ephemeral_disk_size' => 20480  # Disk in MiB
}

# Returns: Hash with instance_type
# { 'instance_type' => 'm1.large', 'root_disk' => { 'size' => 20 } }
```
```

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

### Generate Fake Interface with go:generate Directive

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

Use a `go:generate` directive in your Go source file to automatically generate a fake implementation for an interface. This directive is processed by the `go generate` command.

```go
//go:generate go run github.com/maxbrunsfeld/counterfeiter/v6 . MySpecialInterface

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

```

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

### Configure CPI with Application Credentials

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

Use scoped application credentials for enhanced security instead of standard username/password authentication.

```yaml
---
properties:
  openstack:
    auth_url: http://192.168.0.1:5000/v3
    application_credential_id: abc123def456
    application_credential_secret: secret-value
    region: RegionOne
    endpoint_type: publicURL
    state_timeout: 300
    default_key_name: bosh
    default_security_groups:
      - bosh-sg
```

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

### Generate Release Notes from PRs

Source: https://github.com/cloudfoundry/bosh-openstack-cpi-release/blob/master/src/openstack_cpi_golang/vendor/github.com/gophercloud/gophercloud/RELEASE.md

Generate a formatted list of PRs for release notes using jq. This output should be added to the CHANGELOG.md file.

```shell
jq -r '.[] | "* [GH-\(.number)](\(.url)) \(.title)"' prs.json
```

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

### Create Authenticated Client Provider

Source: https://github.com/cloudfoundry/bosh-openstack-cpi-release/blob/master/src/openstack_cpi_golang/vendor/github.com/gophercloud/gophercloud/README.md

Obtain a `ProviderClient` struct by passing the `AuthOptions` to `openstack.AuthenticatedClient()`. This client contains the necessary authentication details to interact with OpenStack APIs.

```go
provider, err := openstack.AuthenticatedClient(opts)
```

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

### CPI Method: calculate_vm_cloud_properties

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

Maps generic VM requirements to OpenStack-specific cloud properties.

```APIDOC
## calculate_vm_cloud_properties(requirements)

### Description
Maps generic VM requirements (CPU, RAM, disk) to OpenStack-specific cloud properties by finding a matching flavor.

### Parameters
- **requirements** (hash) - Required - Contains 'cpu', 'ram', and 'ephemeral_disk_size'.
```

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

### List Ports by Device and Network

Source: https://github.com/cloudfoundry/bosh-openstack-cpi-release/blob/master/ci/ruby_scripts/spec/assets/expected_api_calls.md

Retrieve a list of network ports associated with a specific device ID and network ID.

```bash
GET /v2.0/ports?device_id=<device_id>&network_id=<network_id>
```

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

### Add Volume Metadata

Source: https://github.com/cloudfoundry/bosh-openstack-cpi-release/blob/master/ci/ruby_scripts/spec/assets/expected_api_calls.md

Attach or update metadata for a specific volume.

```bash
POST /v2/<tenant_id>/volumes/<resource_id>/metadata body: {"metadata":"<metadata>"}
```

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

### Create Compute V2 Service Client

Source: https://github.com/cloudfoundry/bosh-openstack-cpi-release/blob/master/src/openstack_cpi_golang/vendor/github.com/gophercloud/gophercloud/README.md

Generate a Compute V2 service client using the authenticated provider and endpoint options, including the region. This client is used for Compute API operations.

```go
client, err := openstack.NewComputeV2(provider, gophercloud.EndpointOpts{
	Region: os.Getenv("OS_REGION_NAME"),
})
```

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

### Configure BOSH OpenStack Deployment Manifest

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

Defines instance groups, VM types with cloud properties, and network configurations for an OpenStack environment.

```yaml
instance_groups:
- name: api
  instances: 3
  vm_type: default
  stemcell: default
  networks:
  - name: default
    static_ips:
    - 10.0.0.10
    - 10.0.0.11
    - 10.0.0.12
  - name: vip
    static_ips:
    - 203.0.113.10

vm_types:
- name: default
  cloud_properties:
    instance_type: m1.large
    availability_zone: nova
    # Boot from volume configuration
    boot_from_volume: true
    root_disk:
      size: 30  # GiB
    # Scheduler hints for server groups
    scheduler_hints:
      group: anti-affinity-group-uuid
    # Load balancer pool integration
    loadbalancer_pools:
    - name: web-pool
      port: 80
    - name: https-pool
      port: 443
    # VRRP allowed address pairs
    allowed_address_pairs: 10.0.0.100

networks:
- name: default
  type: manual
  subnets:
  - range: 10.0.0.0/24
    gateway: 10.0.0.1
    dns: [8.8.8.8]
    reserved: [10.0.0.1-10.0.0.9]
    static: [10.0.0.10-10.0.0.50]
    cloud_properties:
      net_id: network-uuid
      security_groups:
      - bosh-sg
      - cf-sg

- name: vip
  type: vip
```

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

### Counterfeiter CLI Usage

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

This shows the command-line interface usage for Counterfeiter, detailing the available flags for customization such as output path, fake name, header files, and specifying the source interface.

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

```

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

### Vet Go code

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

Runs the Go vet tool to identify suspicious constructs in the codebase.

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

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

### Update Go Modules

Source: https://github.com/cloudfoundry/bosh-openstack-cpi-release/blob/master/src/openstack_cpi_golang/vendor/github.com/gophercloud/gophercloud/README.md

Run `go mod tidy` to update your go.mod file after referencing a Gophercloud package.

```shell
go mod tidy
```

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

### OpenStack Nova API - List Security Groups

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

Retrieves a list of available security groups. Requires tenant ID.

```bash
GET /v2.1/<tenant_id>/os-security-groups
```

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

### Run Unit Tests

Source: https://github.com/cloudfoundry/bosh-openstack-cpi-release/blob/master/CONTRIBUTING.md

Execute the CPI Ruby unit tests using the provided script.

```bash
./scripts/test-unit
```

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

### Update CHANGELOG.md

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

Generates a list of changes since the last tag and prepends them to the CHANGELOG.md file.

```bash
LAST_VERSION=$(git tag --sort=version:refname | tail -n1)
CHANGES=$(git log --pretty=format:'- %s [%h]' HEAD...$LAST_VERSION)
echo -e "## NEXT\n\n$CHANGES\n\n### Features\n\n### Fixes\n\n### Maintenance\n\n$(cat CHANGELOG.md)" > CHANGELOG.md
```

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

### Run Ginkgo tests

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

Executes all tests in the project recursively in parallel.

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

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

### Generate Multiple Fakes with counterfeiter:generate Directive

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

When a package has multiple interfaces requiring fake implementations, use the `counterfeiter:generate` directive to specify which interfaces should have fakes generated. This approach is useful for managing numerous directives within a single package.

```go
//go:generate go run github.com/maxbrunsfeld/counterfeiter/v6 -generate

//counterfeiter:generate . MySpecialInterface
type MySpecialInterface interface {
	DoThings(string, uint64) (int, error)
}

//counterfeiter:generate . MyOtherInterface
type MyOtherInterface interface {
	DoOtherThings(string, uint64) (int, error)
}

```