### Example GET Request

Source: https://github.com/emissary-ingress/emissary/blob/main/pkg/ambex/README.md

Demonstrates how to make a GET request to the /get endpoint and view the response headers and body.

```bash
curl localhost:8080/get
```

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

### Setup Diagd Virtual Environment

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Instructions for setting up a Python virtual environment to work on 'diagd'. This includes creating the environment, activating it, installing dependencies, and performing an editable installation of the ambassador package.

```bash
# Create a virtualenv named venv with all the python requirements
# installed.
python3 -m venv venv
. venv/bin/activate
# If you're doing this in Datawire's apro.git, then:
cd ambassador
# Update pip and install dependencies
pip install --upgrade pip
pip install orjson    # see below
pip install -r builder/requirements.txt
# Created an editable installation of ambassador:
pip install -e python/
# Check that we do indeed have diagd in our path.
which diagd
# If you're doing this in Datawire's apro.git, then:
cd ..
```

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

### Example Hello Request

Source: https://github.com/emissary-ingress/emissary/blob/main/pkg/ambex/README.md

Demonstrates how to make a request to the /hello endpoint and view the response.

```bash
curl localhost:8080/hello
```

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

### Start Ambex with configuration directory

Source: https://github.com/emissary-ingress/emissary/blob/main/pkg/ambex/README.md

Starts the ambex service, loading configuration from the specified directory. Use the --watch flag to enable automatic reloading on file changes.

```shell
go run github.com/datawire/ambassador/cmd/busyambassador ambex ./example/ambex/
```

```shell
go run github.com/datawire/ambassador/cmd/busyambassador ambex --watch ./example/ambex/
```

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

### Test Website Changes Locally

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/RELEASING.md

Before submitting a pull request, you can test your website changes locally. Run `yarn install` to install dependencies, then `yarn start` to launch the local development server. Access the site at `localhost:8000`.

```bash
yarn install && yarn start
```

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

### Run Full E2E Test Cycle

Source: https://github.com/emissary-ingress/emissary/blob/main/test/e2e/README.md

Execute the complete end-to-end testing cycle, including cluster setup, image building, Emissary installation, and test execution.

```bash
make e2e/local
```

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

### Generate and Report Dependencies

Source: https://github.com/emissary-ingress/emissary/blob/main/tools/src/py-mkopensource/README.md

Installs requirements, generates a dependency list using `pip show`, and then processes it with `py-mkopensource`. The output is piped directly to the tool.

```shell
pip3 --disable-pip-version-check install -r requirements.txt
pip3 --disable-pip-version-check freeze --exclude-editable | cut -d= -f1 | xargs pip show | sed 's/^---$//' >dependenncies.txt
echo '' >>dependenncies.txt
cat dependenncies.txt | ./py-mkopensource
```

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

### Start Envoy with ADS bootstrap configuration

Source: https://github.com/emissary-ingress/emissary/blob/main/pkg/ambex/README.md

Launches an Envoy proxy instance with a bootstrap configuration that points to the ADS service. Ensure the Envoy configuration file is correctly set up.

```shell
envoy -l debug -c ./example/envoy/bootstrap-ads.yaml
```

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

### WebSocketMapping Variant Example

Source: https://github.com/emissary-ingress/emissary/blob/main/python/tests/src/tests/README.md

This example shows how to define a `WebSocketMapping` as a subclass of `MappingTest`. It iterates through different `ServiceType` variants to create new instances with appropriate names.

```python
class WebSocketMapping(MappingTest):
    ...

    @classmethod
    def variants(cls):
        for st in variants(ServiceType):
            yield cls(st, name="{self.target.name}")
```

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

### Install Emissary-Ingress via Helm

Source: https://context7.com/emissary-ingress/emissary/llms.txt

Installs the Emissary-Ingress CRDs and the gateway itself using Helm. Ensure the CRDs chart is installed first. The gateway installation can be configured with replica count.

```bash
# Add the GHCR OCI Helm registry (no helm repo add needed for OCI)
# Step 1: Install the CRDs chart (includes conversion webhook for legacy v1/v2 CRD support)
helm install emissary-crds \
  oci://ghcr.io/emissary-ingress/emissary-crds-chart \
  --version 4.0.1 \
  --namespace emissary-system \
  --create-namespace \
  --set enableLegacyVersions=false  # set true to support v2 CRDs, also set enableV1=true for v1

# Wait for the webhook to be ready before installing emissary itself
kubectl wait --timeout=90s --for=condition=available deployment \
  emissary-crds -n emissary-system

# Step 2: Install the Emissary gateway
helm install emissary \
  oci://ghcr.io/emissary-ingress/emissary-ingress \
  --version 4.0.1 \
  --namespace emissary \
  --create-namespace \
  --set replicaCount=3

# Verify installation
kubectl get pods -n emissary
# NAME                        READY   STATUS    RESTARTS   AGE
# emissary-7d6b5b5d9c-4xhkp   1/1     Running   0          2m
# emissary-7d6b5b5d9c-8lzvt   1/1     Running   0          2m
# emissary-7d6b5b5d9c-r9qmf   1/1     Running   0          2m
```

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

### End-to-End Emissary-Ingress Deployment Example

Source: https://context7.com/emissary-ingress/emissary/llms.txt

Complete Kubernetes manifests to deploy a backend service and expose it via Emissary-Ingress. Includes Deployment, Service, Listener, Host, and Mapping resources.

```yaml
# 1. Deploy the backend service
apiVersion: apps/v1
kind: Deployment
metadata:
  name: quote
  namespace: default
spec:
  replicas: 1
  selector:
    matchLabels:
      app: quote
  template:
    metadata:
      labels:
        app: quote
    spec:
      containers:
        - name: backend
          image: docker.io/datawire/quote:0.5.0
          ports:
            - name: http
              containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: quote
  namespace: default
spec:
  ports:
    - name: http
      port: 80
      targetPort: 8080
  selector:
    app: quote

---
# 2. Create the Listener (port 8080)
apiVersion: getambassador.io/v3alpha1
kind: Listener
metadata:
  name: http-listener
  namespace: emissary
spec:
  port: 8080
  protocol: HTTP
  securityModel: INSECURE
  hostBinding:
    namespace:
      from: ALL

---
# 3. Create the Host
apiVersion: getambassador.io/v3alpha1
kind: Host
metadata:
  name: wildcard-host
  namespace: emissary
spec:
  hostname: "*"
  requestPolicy:
    insecure:
      action: Route

---
# 4. Create the Mapping to route /quote/ to the quote service
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: quote-mapping
  namespace: default
spec:
  hostname: "*"
  prefix: /quote/
  service: quote.default

---
# 5. Test (after getting the LoadBalancer external IP):
# EMISSARY_IP=$(kubectl get svc emissary -n emissary -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
# curl http://$EMISSARY_IP/quote/
# Expected:
# {
#   "server": "quote-backend",
#   "quote": "Perfection is achieved, not when there is nothing more to add...",
#   "time": "2024-01-01T00:00:00.000Z"
# }

```

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

### Open Envoy Build Container Shell

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Starts the Envoy build container and opens an interactive bash shell session. The '_cxx/envoy' directory is volume-mounted, and the user is set to 'envoybuild' for hermetic builds.

```shell
make envoy-shell
```

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

### TCPMapping CRD Examples

Source: https://context7.com/emissary-ingress/emissary/llms.txt

Examples of the TCPMapping CRD for routing raw TCP or TLS-passthrough connections to backend services.

```APIDOC
## TCPMapping CRD

### Description
Routes non-HTTP protocols (databases, SSH, raw TCP) by mapping ports and optionally SNI hostnames to backend services.

### Examples

#### TCP Passthrough for PostgreSQL
```yaml
apiVersion: getambassador.io/v3alpha1
kind: TCPMapping
metadata:
  name: postgres-tcp
  namespace: emissary
spec:
  port: 5432
  service: postgres.database:5432
```

#### TLS Passthrough by SNI Hostname
```yaml
apiVersion: getambassador.io/v3alpha1
kind: TCPMapping
metadata:
  name: internal-db-tls
  namespace: emissary
spec:
  port: 5433
  host: db.internal.example.com   # match by SNI
  service: internal-db.data:5433
  tls: upstream-tls               # name of a TLSContext for origination to upstream
  idle_timeout_ms: "300000"       # 5 minute idle timeout
```

#### TCP Listener (Required for Exposure)
```yaml
apiVersion: getambassador.io/v3alpha1
kind: Listener
metadata:
  name: tcp-listener-5432
  namespace: emissary
spec:
  port: 5432
  protocol: TCP
  securityModel: INSECURE
  hostBinding:
    namespace:
      from: ALL
```
```

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

### Creating Release Branch

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/RELEASING.md

Create a new branch for the release. Do not name branches starting with 'release/'.

```bash
git checkout -b rel/0.84.0
```

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

### Adding a custom linter to 'make lint'

Source: https://github.com/emissary-ingress/emissary/blob/main/build-aux/docs/intro.md

Integrate a custom linter like 'flake8' into the 'make lint' target. This example shows how to define a separate rule for the linter and then depend on it from the 'lint' target.

```makefile
lint: flake8
flake8:
	flake8 mypackage/
.PHONY: flake8
```

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

### Basic HTTP Mapping

Source: https://context7.com/emissary-ingress/emissary/llms.txt

Route HTTP requests with a specific prefix to a backend service. This example shows routing '/api/' requests to the 'quote' service and stripping the prefix.

```yaml
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: quote-backend
  namespace: emissary
spec:
  hostname: "api.example.com"
  prefix: /api/
  service: quote.default           # <service>.<namespace>
  rewrite: /                       # strip /api/ prefix before forwarding
  timeout_ms: 3000
  idle_timeout_ms: 60000
```

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

### Build Emissary-ingress within a Docker Container

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

This sequence of commands allows building Emissary-ingress inside a Docker container, leveraging Docker-in-Docker. It includes pulling the Docker image, running it with volume mounting for the Docker socket, installing build dependencies, cloning the repository, and initiating the build.

```bash
docker pull docker:latest
```

```bash
docker run --rm -v /var/run/docker.sock:/var/run/docker.sock -it docker:latest sh
```

```bash
apk add --update --no-cache bash build-base go curl rsync python3 python2 git libarchive-tools gawk jq
```

```bash
git clone https://github.com/emissary-ingress/emissary.git && cd emissary
```

```bash
make images
```

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

### Configure Zipkin Tracing

Source: https://context7.com/emissary-ingress/emissary/llms.txt

Configure Emissary to emit trace spans to an external collector using the Zipkin driver. This example shows how to set up Zipkin-compatible tracing, including sampling rates and custom tags.

```yaml
# Zipkin-compatible tracing (works with Jaeger's Zipkin endpoint)
apiVersion: getambassador.io/v3alpha1
kind: TracingService
metadata:
  name: tracing
  namespace: emissary
spec:
  service: jaeger-collector.observability:9411
  driver: zipkin
  sampling:
    overall: 100               # sample 100% of requests
  config:
    collector_endpoint: "/api/v2/spans"
    collector_endpoint_version: HTTP_JSON
    trace_id_128bit: true
    shared_span_context: false
  custom_tags:
    - tag: "deployment.environment"
      literal:
        value: "production"
    - tag: "k8s.pod.name"
      environment:
        name: "HOSTNAME"
        default_value: "unknown"
    - tag: "x-request-id"
      request_header:
        name: "x-request-id"
```

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

### Build Targets

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Use 'make help' and 'make targets' to discover available build targets and their documentation.

```bash
make help
```

```bash
make targets
```

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

### AuthService CRD Examples

Source: https://context7.com/emissary-ingress/emissary/llms.txt

Examples of the AuthService CRD for delegating request authentication to external HTTP or gRPC services.

```APIDOC
## AuthService CRD

### Description
Registers an external authentication service that Emissary calls before forwarding requests. Supports HTTP or gRPC protocols.

### Examples

#### HTTP-based External Auth Service
```yaml
apiVersion: getambassador.io/v3alpha1
kind: AuthService
metadata:
  name: ext-auth
  namespace: emissary
spec:
  auth_service: "auth-service.auth-system:3000"
  proto: http
  path_prefix: "/extauth"          # prepend this path when calling the auth service
  timeout_ms: 5000
  allowed_request_headers:
    - Authorization
    - Cookie
    - X-Api-Key
  allowed_authorization_headers:
    - X-User-Id
    - X-User-Email
    - Set-Cookie
  failure_mode_allow: false        # deny traffic if auth service is unreachable
  include_body:
    max_bytes: 4096
    allow_partial: true            # forward partial body if request exceeds max_bytes
  status_on_error:
    code: 503                      # return 503 when auth service errors
```

#### gRPC-based Auth Service
```yaml
apiVersion: getambassador.io/v3alpha1
kind: AuthService
metadata:
  name: grpc-ext-auth
  namespace: emissary
spec:
  auth_service: "grpc-auth.auth-system:50051"
  proto: grpc
  protocol_version: v3
  timeout_ms: 2000
  add_auth_headers:
    x-gateway-name: emissary
  circuit_breakers:
    - priority: default
      max_connections: 50
      max_requests: 100
```
```

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

### Set Up Development Environment for Testing

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Before running tests, set the `DEV_REGISTRY` and `DEV_KUBECONFIG` environment variables. Ensure you are logged into your development Docker registry and have the necessary permissions.

```bash
export DEV_REGISTRY=<your-dev-docker-registry>
```

```bash
export DEV_KUBECONFIG=<your-dev-kubeconfig>
```

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

### Preparing Release Notes

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/RELEASING.md

Use `make release-prep` to update CHANGELOG.md. This command will prompt for release notes, which should be pasted in during the make process.

```bash
make release-prep
```

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

### Get Emissary LoadBalancer IP Address (GKE/Azure)

Source: https://github.com/emissary-ingress/emissary/blob/main/charts/emissary-ingress/templates/NOTES.txt

For GKE and Azure, use this command to get the LoadBalancer IP address. Note that it may take a few minutes for the IP to become available.

```bash
export SERVICE_IP=$(kubectl get svc --namespace {{ include "ambassador.namespace" .}} {{ include "ambassador.fullname" . }} -o jsonpath='{.status.loadBalancer.ingress[0].ip}')
echo http://$SERVICE_IP:{{ .Values.service.port }}
```

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

### Minimal MappingTest Instantiation

Source: https://github.com/emissary-ingress/emissary/blob/main/python/tests/src/tests/README.md

This demonstrates the minimal way to instantiate a `MappingTest` by providing an HTTP echo service as the target.

```python
MappingTest(HTTP())
```

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

### Update License Documentation

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Run this command after adding or updating dependencies to regenerate license and dependency files.

```bash
make generate
```

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

### Mapping CRD Examples

Source: https://context7.com/emissary-ingress/emissary/llms.txt

Examples of the Mapping CRD for configuring HTTP routing with advanced features like CORS, retries, header manipulation, circuit breaking, gRPC routing, and HTTP redirects.

```APIDOC
## Mapping CRD

### Description
Configures routing for HTTP and gRPC traffic, including advanced features.

### Examples

#### Full-featured Mapping
```yaml
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: full-featured-mapping
  namespace: emissary
spec:
  hostname: "*.example.com"
  prefix: /service/
  service: my-service.production
  cors:
    origins:
      - "https://app.example.com"
      - "https://admin.example.com"
    methods: [GET, POST, PUT, DELETE, OPTIONS]
    headers: [Content-Type, Authorization]
    credentials: true
    max_age: "86400"
  retry_policy:
    retry_on: "5xx,gateway-error,connect-failure"
    num_retries: 3
    per_try_timeout: "1s"
  circuit_breakers:
    - priority: default
      max_connections: 100
      max_pending_requests: 50
      max_requests: 200
      max_retries: 5
  add_request_headers:
    x-forwarded-host:
      value: "%REQ(:AUTHORITY)%"
  remove_response_headers:
    - x-powered-by
    - server
  load_balancer:
    policy: round_robin
```

#### gRPC Routing with WebSocket Upgrade
```yaml
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: grpc-service
  namespace: emissary
spec:
  hostname: "grpc.example.com"
  prefix: /helloworld.Greeter/
  service: greeter-service.default:50051
  grpc: true
  allow_upgrade:
    - websocket
```

#### HTTP Redirect Mapping
```yaml
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: www-redirect
  namespace: emissary
spec:
  hostname: "www.example.com"
  prefix: /
  service: example.com             # destination host
  host_redirect: true
  redirect_response_code: 301
```

#### Active Health Checking
```yaml
apiVersion: getambassador.io/v3alpha1
kind: Mapping
metadata:
  name: healthy-service
  namespace: emissary
spec:
  hostname: "api.example.com"
  prefix: /health-checked/
  service: backend.default
  health_checks:
    - timeout: 3s
      interval: 5s
      unhealthy_threshold: 2
      healthy_threshold: 1
      health_check:
        http:
          path: /healthz
          expected_statuses:
            - min: 200
              max: 299
```
```

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

### Run Emissary-ingress Entrypoint

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Use this command to run the main entrypoint of Emissary-ingress locally. This requires the 'go' toolchain and will attempt to launch 'diagd' and 'envoy'.

```bash
go run ./cmd/busyambassador entrypoint
```

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

### Tagging Master for RC Release

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/RELEASING.md

Tag the master branch with a release candidate tag. This tag must start with 'v'.

```bash
git tag v0.77.0-rc.1 master
git push --tags origin master
```

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

### Ambex Configuration Reload

Source: https://github.com/emissary-ingress/emissary/blob/main/pkg/ambex/README.md

Shows how to edit configuration files in the ./example/ambex/ directory and trigger a reload. Use the --watch flag for instantaneous reloads or signal the process with 'killall -HUP ambex' for manual triggers.

```bash
killall -HUP ambex
```

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

### Change Loglevel at Runtime

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Adjust the log level for diagd and Envoy by sending a GET request to the diagnostic endpoint. Note that this does not affect the AES amb-sidecar.

```console
curl localhost:8877/ambassador/v0/diag/?loglevel=debug
```

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

### Get Emissary LoadBalancer IP Address (AWS)

Source: https://github.com/emissary-ingress/emissary/blob/main/charts/emissary-ingress/templates/NOTES.txt

For AWS, use this command to retrieve the LoadBalancer hostname. It may take a few minutes for the hostname to be available.

```bash
export SERVICE_IP=$(kubectl get svc --namespace {{ include "ambassador.namespace" .}} {{ include "ambassador.fullname" . }} -o jsonpath='{.status.loadBalancer.ingress[0].hostname}')
echo http://$SERVICE_IP:{{ .Values.service.port }}
```

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

### Run Specific Go or Python Tests

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

To run specific Go tests, use `make gotest GOTEST_PKGS=./cmd/entrypoint GOTEST_ARGS="-run TestName"`. For specific Python tests, use `make pytest PYTEST_ARGS="-k TestName"`.

```bash
make gotest GOTEST_PKGS=./cmd/entrypoint GOTEST_ARGS="-run TestName"
```

```bash
make pytest PYTEST_ARGS="-k TestName"
```

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

### Override Build Architecture

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Set the BUILD_ARCH environment variable to override the default build artifact architecture, for example, to build for Apple Silicon Macs.

```bash
BUILD_ARCH=linux/arm64 make images
```

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

### Basic GNU Make Rule

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/gnu-make.md

Defines a target, its dependencies, and the command to execute when the target is out of date. Use this for simple build steps.

```makefile
target: dependency1 dependency2
	command to run
```

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

### Tagging for GA Release

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/RELEASING.md

Tag the release branch with a GA tag. This tag must start with 'v'. CI will then retag the latest RC image as the GA image.

```bash
git tag v0.77.0
```

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

### Clone Repository

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Clone your forked repository locally to begin making changes.

```shell
git clone <your-fork>
```

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

### Get Emissary NodePort IP Address

Source: https://github.com/emissary-ingress/emissary/blob/main/charts/emissary-ingress/templates/NOTES.txt

Use these commands when Emissary is exposed via a NodePort service. It retrieves the NodePort and the IP address of a node to construct the service URL.

```bash
export NODE_PORT=$(kubectl get --namespace {{ include "ambassador.namespace" .}} -o jsonpath="{.spec.ports[0].nodePort}" services {{ include "ambassador.fullname" . }})
export NODE_IP=$(kubectl get nodes --namespace {{ include "ambassador.namespace" .}} -o jsonpath="{.items[0].status.addresses[0].address}")
echo http://$NODE_IP:$NODE_PORT
```

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

### Prepare .Y Bump

Source: https://github.com/emissary-ingress/emissary/wiki/Starting-work-on-a-new-.Y-release

Run this script to create a commit, branches, and tags for a new .Y release. It will provide a git push command upon completion.

```bash
./releng/prepare-y-bump
```

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

### Build Envoy and Container Separately

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

A sequence of commands to build Envoy, then its container image, and finally test Emissary-ingress without pushing the container. Useful when not pushing intermediate images.

```shell
make build-envoy
make build-base-envoy-image
make test
```

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

### Running Go Programs in Cleanup Rules

Source: https://github.com/emissary-ingress/emissary/blob/main/build-aux/HACKING.md

When cleaning up Go programs, change to the program's source directory and use 'go run .'. This ensures the program is built and executed correctly within its own context.

```makefile
cd $(dir $(_myfile.mk))bin-go/PROGRAM && GO111MODULE=on go run . ARGS...
```

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

### Configure OpenTelemetry Tracing

Source: https://context7.com/emissary-ingress/emissary/llms.txt

Configure Emissary to emit trace spans to an external collector using the OpenTelemetry driver. This example demonstrates setting up OpenTelemetry tracing with specific sampling configurations.

```yaml
# OpenTelemetry tracing
apiVersion: getambassador.io/v3alpha1
kind: TracingService
metadata:
  name: otel-tracing
  namespace: emissary
spec:
  service: otel-collector.observability:4317
  driver: opentelemetry
  sampling:
    client: 50
    random: 50
    overall: 50
```

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

### Standard .mk Snippet Header

Source: https://github.com/emissary-ingress/emissary/blob/main/build-aux/docs/conventions.md

All .mk snippets must begin with a header comment including a copyright statement, a brief description, and section headings for eager inputs, lazy inputs, outputs, and common.mk targets. Additional sections may be required for dependencies on other snippets.

```make
# Copyright statement.
#
# A sentence or two introducing what this file does.
#
## Section heading ##
#  - type: item
#  - type: item
## Section heading ##
#  - item
#  - item
#
# High-level prose documentation.

```

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

### Deploy Emissary-ingress to Kubernetes

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Generate Helm charts and Kubernetes configurations with your container image swapped in, and apply them to your cluster. Verify the deployment by checking the Emissary pod status in the `ambassador` namespace.

```bash
# generate helm charts and K8's Configs with your container swapped in and apply them to your cluster
make deploy

# check your cluster to see if emissary is running
# note: kubectl doesn't know about  DEV_KUBECONFIG so you may need to ensure KUBECONFIG is pointing to the correct cluster
kubectl get pod -n ambassador
```

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

### Load Ambassador Configuration Resources

Source: https://github.com/emissary-ingress/emissary/blob/main/python/README.md

Instantiate an `ambassador.Config` object and load a list of `ACResource` objects into it. This method should only be called once with all resources.

```python
aconf: Config = Config()
aconf.load_all(resources: List[ACResource])
```

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

### Clean Build Environment

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Use `make clobber` to remove all derived objects and cached artifacts for a clean build. Use `make clean` to remove derived objects but preserve caches.

```bash
make clobber
```

```bash
make clean
```

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

### Configure gRPC Access Log Service

Source: https://context7.com/emissary-ingress/emissary/llms.txt

Configure Emissary to stream access logs to an external gRPC server using the Access Log Service API. This example specifies the service endpoint, driver configuration, and additional log headers.

```yaml
# gRPC Access Log Service
apiVersion: getambassador.io/v3alpha1
kind: LogService
metadata:
  name: grpc-access-log
  namespace: emissary
spec:
  service: log-collector.logging:50051
  driver: http
  grpc: true
  protocol_version: v3
  flush_interval_time: 1         # flush every 1 second
  flush_interval_byte_size: 32768
  driver_config:
    additional_log_headers:
      - header_name: "x-request-id"
        during_request: true
        during_response: true
      - header_name: "x-user-id"
        during_request: true
        during_response: false
```

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

### Rebase Patch Branch on Base Branch

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Before starting work on a patch branch, ensure your local master is up-to-date and then rebase your patch branch onto master to maintain a linear commit history. This process may involve resolving merge conflicts.

```shell
# first, make sure you pull latest upstream changes
git fetch upstream
git checkout master
git pull -ff upstream/master

# checkout patch branch and rebase interactive
# you may have merge conflicts you need to resolve
git checkout my-patch-branch
git rebase -i master
```

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

### Variable Input/Output Convention

Source: https://github.com/emissary-ingress/emissary/blob/main/build-aux/docs/conventions.md

Use 'Variable' to denote variables. For inputs, include '?= value' if a default value exists. For outputs, include '= value' or '?= value' to document the variable's content, indicating if it can be overridden.

```make
Variable
```

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

### Push Docker Images to Registry

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Retag and push the built Docker images to your configured container registry. Ensure Docker is logged in and has push permissions. You can also use `make env` or `make export` to view environment variables or get export-friendly output.

```bash
# re-tags the images and pushes them to your configured container registry
# docker must be able to login to your registry and you have to have push permissions
make push

# you can view the newly tag images by running
docker images | grep <your -registry>

# alternatively, we have two make targets that provide information as well
make env

# or in a bash export friendly format
make export
```

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

### Run All Emissary-ingress Tests

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Execute `make test` to run all tests. Use `make gotest` for all Go tests and `make pytest` for all Python tests.

```bash
make test
```

```bash
make gotest
```

```bash
make pytest
```

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

### Target Output Convention

Source: https://github.com/emissary-ingress/emissary/blob/main/build-aux/docs/conventions.md

Use 'Target(s)' to indicate that the snippet defines rules to create specified file(s). List each target separately, or use the plural 'Targets' for expressions covering a wide range of files.

```make
Target(s)
```

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

### Initialize and Branch Envoy Sources

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Fetch the current Envoy sources vendored with Emissary-ingress and create a new branch for modifications. This command should be run from your `emissary.git` checkout.

```shell
make $PWD/_cxx/envoy
git -C _cxx/envoy checkout -b YOUR_BRANCHNAME
```

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

### List Kubernetes Resource Statuses

Source: https://github.com/emissary-ingress/emissary/blob/main/cmd/kubestatus/README.md

Use this command to list the statuses of Kubernetes resources matching the specified kind and selectors. No updates are made by default.

```bash
kubestatus service -f metadata.name=foo
```

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

### Build Base Envoy Docker Image

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Generates a new 'base-envoy' container image using the release outputs from building Envoy binaries.

```shell
make build-base-envoy-image
```

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

### Build Envoy Binaries

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Builds the Envoy binaries using the upstream Envoy project's build container. Outputs are placed in '_cxx/envoy-docker-build'.

```shell
make build-envoy
```

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

### Outputs Convention

Source: https://github.com/emissary-ingress/emissary/blob/main/build-aux/docs/conventions.md

Outputs section lists targets, variables, etc. that the snippet defines. This includes rules to create files, .PHONY targets, variables, functions, and executables.

```make
## Outputs ##
```

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

### Build Docker Images

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Build the necessary Docker containers for Emissary-ingress, including the main Emissary container and test client/server containers. This command may take time on the first run as base images are built and cached.

```bash
# This will pull and build the necessary docker containers and produce multiple containers.
# If this is the first time running this command it will take a little bit while the base images are built up and cached.
make images

# verify containers were successfully created, you should also see some of the intermediate builder containers as well
docker images | grep emissary.local
```

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

### Create and Push GA Git Tags

Source: https://github.com/emissary-ingress/emissary/wiki/Release-Process-(2.3.z)

Use these commands to create and push annotated Git tags for a general availability (GA) Emissary release and its Helm chart. Update the version variables to reflect the GA versions.

```shell
version=2.2.0
chart_version=7.3.0
git tag --annotate --message="Emissary ${version} GA release" "v${version}"
git tag --annotate --message="Emissary Helm chart ${chart_version} GA release for Emissary ${version}" "chart/v${chart_version}"
git push origin "v${version}" "chart/v${chart_version}"
```

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

### Deploy Development Container

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Run this command to recompile, rebuild, push, and re-deploy Emissary-ingress to your cluster for live testing.

```shell
make deploy
```

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

### Adding targets to 'make help'

Source: https://github.com/emissary-ingress/emissary/blob/main/build-aux/docs/intro.md

Add custom targets to the 'make help' output by using a magic comment '##' followed by a description. This makes your custom targets visible in the help information.

```makefile
frob: ## Frobnicate the splorks
```

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

### Create and Push RC Git Tags

Source: https://github.com/emissary-ingress/emissary/wiki/Release-Process-(2.3.z)

Use these commands to create and push annotated Git tags for an Emissary release candidate and its corresponding Helm chart. Ensure the version variables are set correctly.

```shell
version=2.2.0-rc.3
chart_version=7.3.0-rc.3
git tag --annotate --message="Emissary ${version} release candidate" "v${version}"
git tag --annotate --message="Emissary Helm chart ${chart_version} release candidate for Emissary ${version}" "chart/v${chart_version}"
git push origin "v${version}" "chart/v${chart_version}"
```

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

### Create and Push Emissary and Chart Git Tags

Source: https://github.com/emissary-ingress/emissary/wiki/Release-Process-(2.3.z)

Use this command to create and push both the Emissary version tag and its corresponding Helm chart tag simultaneously. It's crucial that both tags are pushed together to ensure CI processes function correctly.

```shell
version=2.2.0-rc.3
chart_version=7.3.0-rc.3
git tag --annotate --message="Emissary ${version} release" "v${version}"
git tag --annotate --message="Emissary Helm chart ${chart_version} release for Emissary ${version}" "chart/v${chart_version}"
git push origin "v${version}" "chart/v${chart_version}"
```

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

### Redeploy Emissary with Local Images

Source: https://github.com/emissary-ingress/emissary/blob/main/test/e2e/README.md

Build Emissary images and install/upgrade the charts, useful when code changes require redeployment without cluster recreation. Explicitly set the VERSION to avoid Kubernetes label limits.

```bash
make images && make VERSION=v4.0.0-local e2e/install
```

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

### Run Envoy Test Suite

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Executes the Envoy test suite within the build Docker container against the Envoy code in the '_cxx/envoy' folder.

```shell
make check-envoy
```

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

### Test with Private Docker Repository

Source: https://github.com/emissary-ingress/emissary/blob/main/DevDocumentation/CONTRIBUTING.md

Configure these environment variables to enable the test machinery to create an imagePullSecret for pulling images from a private Docker repository.

```bash
export DEV_USE_IMAGEPULLSECRET=true
export DOCKER_BUILD_USERNAME=...
export DOCKER_BUILD_PASSWORD=...
```