### Start Dev Environment

Source: https://github.com/kumahq/kuma/blob/master/CLAUDE.md

Starts a development environment using k3d and skaffold.

```bash
make k3d/cluster/start && skaffold dev
```

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

### Install Development Tools

Source: https://github.com/kumahq/kuma/blob/master/CLAUDE.md

Installs necessary development tools for the project. This command runs `mise install` and `buf dep update`.

```bash
make install
```

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

### Install Development Tools with Mise

Source: https://github.com/kumahq/kuma/blob/master/DEVELOPER.md

Installs the necessary development tools managed by mise.

```bash
make install
```

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

### Example System Resource Naming (Kuma Resource)

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/084-finalized-schemes-for-unified-envoy-resources-and-stats-naming-formats.md

An example illustrating the `system_<kri>` format for a specific Kuma resource, such as a MeshGlobalRateLimit policy.

```text
system_kri_mgrl___kong-mesh-system_global-rate-limit-policy_
```

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

### Envoy Listener Example (JSON Format)

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/070-resource-identifier.md

Demonstrates a workaround to get Envoy listener information in JSON format by using the `format=json` query parameter, avoiding colon-separated issues.

```bash
$ curl http://localhost:9901/listeners\?format\=json
{
 "listener_statuses": [
  {
   "name": "inbound:127.0.0.1:8000",
   "local_address": {
    "socket_address": {
     "address": "127.0.0.1",
     "port_value": 8000
    }
   }
  }
 ]
}
```

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

### System Naming Examples (Internal)

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/084-finalized-schemes-for-unified-envoy-resources-and-stats-naming-formats.md

Examples of system naming for internal components, including DNS, Prometheus metrics, and KRI-derived system resources.

```text
system_dynamicconfig_dns
```

```text
system_metrics_prometheus
```

```text
system_kri_mgrl___kong-mesh-system_global-rate-limit-policy_
```

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

### MeshGatewayInstance Example

Source: https://github.com/kumahq/kuma/blob/master/UPGRADE.md

Example of a MeshGatewayInstance resource. In versions 2.9.x and later, the 'kuma.io/service' tag is automatically generated and cannot be set manually.

```yaml
apiVersion: kuma.io/v1alpha1
kind: MeshGatewayInstance
metadata:
  name: demo-app
  namespace: kuma-demo
  labels:
    kuma.io/mesh: default
```

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

### Instance Discovery Config Example

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/014-multizone-envoy-admin.md

This YAML configuration defines a list of CP instances, including their addresses, inter-CP ports, IDs, and leader status. It's used for discovering active CP instances in a multizone setup.

```yaml
type: Config
name: cp-instances
config: |
  {
    "instances": [
      {
        "address": "192.168.1.100",
        "interCpPort": 5682,
        "id": "<instance_id>",
        "leader": true
      },
      {
        "address": "192.168.1.101",
        "interCpPort": 5682,
        "id": "<instance_id>",
        "leader": false
      },
    ]
  }
```

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

### Kubernetes Service Example

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/041-meshservice-kubernetes-ux.md

This is an example of a standard Kubernetes Service definition.

```yaml
kind: Service
metadata:
  name: redis
  namespace: redis-system
  labels:
    team: db-operators
    kuma.io/mesh: default
spec:
  selector:
    app.kubernetes.io/name: redis
  ports:
  - port: 6739
    targetPort: 6739
    protocol: TCP
  - name: admin
    port: 8080
    protocol: TCP
    appProtocol: http
```

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

### Contextual Naming Examples (ZoneIngress)

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/084-finalized-schemes-for-unified-envoy-resources-and-stats-naming-formats.md

Examples of contextual naming for ZoneIngress resources, specifically for inbound listeners.

```text
self_inbound_zi_10001
```

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

### Policy Inbound Configuration Example (from array)

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/005-policy-matching.md

Illustrates configuring inbound traffic policies using the 'from' array. This example shows different actions (DENY, ALLOW) based on various target references.

```yaml
type: MeshTrafficPermission
mesh: mesh-1
name: permissions
spec:
  targetRef:
    kind: MeshService
    name: backend
  from:
    - targetRef:
        kind: Mesh
        name: mesh-1
      default:
        action: DENY
    - targetRef:
        kind: MeshServiceSubset
        name: backend
        tags:
          version: v2
      default:
        action: ALLOW
    - targetRef:
        kind: MeshSubset
        name: mesh-1
        tags:
          kuma.io/zone: us-east
      default:
        action: ALLOW
```

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

### Contextual Naming Examples (Transparent Proxy)

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/084-finalized-schemes-for-unified-envoy-resources-and-stats-naming-formats.md

Examples of contextual naming for transparent proxy passthrough, specifying direction and IP version.

```text
self_transparentproxy_passthrough_dp_outbound_ipv6
```

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

### Init Container Template Example

Source: https://github.com/kumahq/kuma/blob/master/docs/proposals/custom-sidecar-config.md

An example of a full container specification template for an init container. This approach was considered but deemed less preferable than a patch style.

```yaml
initTemplate: |
  name: kuma-init
  command: {{ .Command }}
  args: {{ .Args }}
  image: {{ .Image }}
  imagePullPolicy: {{ .ImagePullPolicy }}
  resources:
    limits:
      cpu: {{ .Resources.Limits.Cpu }}
      memory: {{ .Resources.Limits.Memory }}
    requests:
      cpu: {{ .Resources.Requests.Cpu }}
      memory: {{ .Resources.Requests.Memory }}
  securityContext:
    capabilities:
      add:
      - NET_ADMIN
      - NET_RAW
    runAsGroup: {{ .SecurityContext.RunAsGroup }}
    runAsNonRoot: true
  terminationMessagePath: {{ .TerminationMessagePath }}
  terminationMessagePolicy: {{ .TerminationMessagePolicy }}
  volumeMounts: {{ .VolumeMounts }}
```

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

### Install New Kuma Control Plane (Kubernetes)

Source: https://github.com/kumahq/kuma/blob/master/UPGRADE.md

Install the new version of the Kuma Control Plane using `kumactl` and `kubectl apply`.

```shell
# using new version of `kumactl`

kumactl install control-plane | kubectl apply -f -
```

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

### Injector Overlay Configuration Example

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/074-spiffe-compliance.md

Example of using overlays to configure the control-plane injector, specifically for adding SPIRE agent socket volumes and volume mounts.

```yaml
runtime:
  kubernetes:
    injector:
        overlay:
            - path: spec.template.spec.volumes.spire-agent-socket
              op: add
              value:
                name: spire-agent-socket
                hostPath:
                  path: /run/spire/sockets
                  type: Directory
            - path: spec.template.spec.containers.kuma-sidecar.volumeMounts.spire-agent-socket
              op: add
              value:
                name: spire-agent-socket
                mountPath: /run/spire/sockets/
                readOnly: true          
```

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

### Kuma Global Configuration Example

Source: https://github.com/kumahq/kuma/blob/master/docs/proposals/multicluster.md

Example configuration for the Kuma Global Control Plane, specifying addresses for remote clusters and their respective gateways.

```yaml
clusters:
- remote:
    address: 192.168.0.2 # Load balancer for many Remote CPs in this cluster
  gateway:
    address: 192.168.0.1 # Load balancer for many gateways in this cluster
- remote:
    address: 192.168.2.2 # Load balancer for many Remote CPs in this cluster
  gateway:
    address: 192.168.2.1 # Load balancer for many gateways in this cluster

```

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

### Example Full KRI Resource Name

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/078-migrating-to-consistent-and-well-defined-naming-for-non-system-envoy-resources-and-stats.md

This example shows the full KRI format for Envoy resource names, which includes all details for traceability.

```plaintext
kri_dp_default_kuma-2_kuma-demo_demo-app-ddd8546d5-vg5ql_5050
```

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

### MeshService and MeshTimeout Policy Example

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/054-policy-on-namespace.md

This example illustrates a MeshService and a MeshTimeout policy referencing it. These resources are synced to zone-2, demonstrating cross-zone policy referencing.

```yaml
# zone-1, producer-timeout references backend service
kind: MeshService
metadata:
  name: backend
  namespace: backend-ns
---
kind: MeshTimeout
metadata:
  name: producer-timeout
  namespace: backend-ns
spec:
  to:
    - targetRef:
        kind: MeshService
        name: backend
```

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

### Contextual Transparent Proxy Passthrough Examples

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/084-finalized-schemes-for-unified-envoy-resources-and-stats-naming-formats.md

Examples for transparent-proxy passthrough resources, including scope and IP version. The scope token is appended to align with the adjusted contextual scheme.

```text
self_transparentproxy_passthrough_dp_inbound_ipv4
self_transparentproxy_passthrough_dp_outbound_ipv6
```

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

### Helm Install Command

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/094-zone-proxy-deployment-model.md

Installs the Kuma Helm chart with a specified values file. This command is used to deploy Kuma, including zone proxies, in a GitOps-friendly manner.

```bash
helm install kuma kumahq/kuma -n kuma-system -f values.yaml
```

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

### Configure DNS Server Domain (YAML)

Source: https://github.com/kumahq/kuma/blob/master/UPGRADE.md

If your `dnsServer.domain` configuration starts with a dot, remove the leading dot to ensure valid hostname generation. This example shows the corrected configuration.

```yaml
# kuma-cp config
dnsServer:
  domain: mesh   # was: .mesh
```

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

### Bootstrap a New Resource

Source: https://github.com/kumahq/kuma/blob/master/docs/guides/new-resource.md

Use this command to create the initial files for a new resource. Specify the resource name, path, API version, and whether it's a policy or has a status field. The `--force` flag overwrites existing files.

```bash
go run ./tools/policy-gen/bootstrap \
  --name YourResource \
  --path pkg/core/resources/apis \
  --version v1alpha1 \
  --is-policy=false \
  --has-status \
  --force
```

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

### Log Info Message - Good Practice

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/003-logging.md

Use lowercase for log messages unless starting with a proper noun. This example shows the correct way to log an informational message.

```go
log.Info("something has happened")
log.Info("Envoy is starting")
```

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

### Method-Specific Access Control with MeshTrafficPermission

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/081-inbound-policies-matches.md

Use this to apply different access rules based on HTTP methods. For example, allow all GET requests while restricting POST requests to specific identities or prefixes.

```yaml
type: MeshTrafficPermission
mesh: default
name: by-backend-owner
spec:
   targetRef:
      kind: Dataplane
      labels:
         app: backend
   default:
      allow:
         - method: GET
         - method: POST
           spiffeId:
              type: Exact
              value: "spiffe://trust-domain.mesh/ns/default/sa/writer-1"
         - method: POST
           spiffeId:
              type: Exact
              value: "spiffe://trust-domain.mesh/ns/default/sa/writer-2"
         - method: POST
           spiffeId:
              type: Prefix
              value: "spiffe://trust-domain.mesh/ns/writers"
```

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

### Resource Rules Configuration Example

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/063-rework-mesh-routes-matching.md

Illustrates how Kuma generates configuration rules for specific resources, merging producer and consumer policies for routes.

```yaml
resourceRules:
  backend.backend-ns:
    conf: $conf1
  backend-route.backend-ns:
    conf: merge($producer_conf, $consumer_conf)
```

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

### Client-side MetadataMatcher Construction

Source: https://github.com/kumahq/kuma/blob/master/pkg/envoy/builders/README.md

This example shows how a client can use the `MetadataMatcher` builder and its configuration functions to construct a `MetadataMatcher` object within a larger builder chain.

```go
SomeBuilderWithMetadataMatcher(...).
  Configure(bldrs_matcher.NewMetadataBuilder().
    Configure(bldrs_matcher.Key(myKey)).
    Configure(bldrs_matcher.ExactValue(myValue)))
```

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

### Example System Resource Name

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/077-naming-system-envoy-resources.md

Illustrates a naming convention for internal Kuma system resources.

```text
kuma:envoy:admin
```

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

### Generate All Tag Combinations for Specific Example in Go

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/007-mesh-traffic-permission.md

Demonstrates the generation of tag combinations for a specific scenario with 'zone' and 'env' tags, including handling duplicate keys and negations.

```go
allTags = []Tag{
	{key: "zone", value: "us-east"},
	{key: "env", value: "dev"},
	{key: "env", value: "prod"},
	
}
```

```go
comb1 = []Tag{
    {key: "zone", value: "us-east"},
    {key: "env", value: "dev"},
    {key: "env", value: "!prod"},
}
comb2 = []Tag{
    {key: "zone", value: "us-east"},
    {key: "env", value: "!dev"},
    {key: "env", value: "prod"},
}
comb3 = []Tag{
    {key: "zone", value: "!us-east"},
    {key: "env", value: "dev"},
    {key: "env", value: "!prod"},
}
comb4 = []Tag{
    {key: "zone", value: "!us-east"},
    {key: "env", value: "!dev"},
    {key: "env", value: "prod"},
}
comb5 = []Tag{
    {key: "zone", value: "us-east"},
    {key: "env", value: "!dev"},
    {key: "env", value: "!prod"},
}
comb6 = []Tag{
    {key: "zone", value: "!us-east"},
    {key: "env", value: "!dev"},
    {key: "env", value: "!prod"},
}
comb7 = []Tag{ // no clients can have env=dev and env=prod at the same time 
    {key: "zone", value: "us-east"},
    {key: "env", value: "dev"},
    {key: "env", value: "prod"},
}
comb8 = []Tag{ // no clients can have env=dev and env=prod at the same time
    {key: "zone", value: "!us-east"},
    {key: "env", value: "dev"},
    {key: "env", value: "prod"},
}
```

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

### Configuration Merge Example

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/063-rework-mesh-routes-matching.md

Illustrates how configurations are merged when policies target different resources, showing the combined effect of default policies and specific overrides.

```yaml
resourceRules:
  backend:
    conf: merge($conf1, $conf3)
  backend-route:
    conf: merge($conf2, $conf4)
```

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

### MeshExternalService Example

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/052-meshexternalservice-api.md

An example of a MeshExternalService resource. This is used in conjunction with HostnameGenerator to determine its domain.

```yaml
kind: MeshExternalService
metadata:
  name: mydomain
  namespace: kuma-system
  labels:
    my.label.io/service: my-service 
    kuma.io/mesh: default
    kuma.io/zone: east-1
    kuma.io/origin: zone
spec:
  destinations:
  - address: 192.168.0.1
    port: 9090 
...
```

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

### Example Commit Message

Source: https://github.com/kumahq/kuma/blob/master/CONTRIBUTING.md

An example of a well-formatted commit message following the Conventional Commits specification.

```text
fix(admin): send HTTP 405 on unsupported method

The appropriate status code when the request method is not supported
on an endpoint it 405. We previously used to send HTTP 404, which
is not appropriate. This updates the Admin API helpers to properly
return 405 on such user errors.

* return 405 when the method is not supported in the Admin API helpers
* add a new test case in the Admin API test suite

Fix #678
```

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

### Run kumactl container image before 2.3.x

Source: https://github.com/kumahq/kuma/blob/master/UPGRADE.md

Example of how to run the kumactl container image with a version prior to 2.3.x.

```sh
docker run kumahq/kumactl:2.2.1 kumactl install transparent-proxy --help
```

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

### Install Delve Debugger

Source: https://github.com/kumahq/kuma/blob/master/DEVELOPER.md

Installs the Delve debugger within the container, matching the Go version specified in go.mod.

```bash
go install github.com/go-delve/delve/cmd/dlv@vCLOSEST_DLV_VERSION
```

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

### Error Handling and Logging - Good Practice

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/003-logging.md

Follow the pattern of either logging an error or returning an error, but not both, unless additional debug information is needed. This example shows correct error handling and logging strategies.

```go
if err != nil {
	return errors.Wrap(err, "more info")
}
...
if err != nil {
	log.Error(err, "more info")
	return nil
}
...
if err != nil {
	log.V(1).Info("much more details about the error")
    return errors.Wrap(err, "more info")
}
```

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

### Run kuma-dp with Transparent Proxy Config

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/071-transparent-proxy-config-map-handling-outside-the-control-plane.md

Use the `--transparent-proxy-config` flag with comma-separated file paths and STDIN to configure transparent proxy settings. Later values override earlier ones.

```sh
CONFIG2=$(mktemp)
CONFIG3=$(mktemp)

echo "{ redirect: { inbound: { port: 2222 } }, wait: 2 }" > "$CONFIG2"
echo "{ redirect: { inbound: { port: 3333 } }, waitInterval: 3 }" > "$CONFIG3"

echo "{ redirect: { inbound: { port: 1111 } }, ipFamilyMode: ipv4 }" | kuma-dp run \
  --transparent-proxy-config "$CONFIG2,$CONFIG3" \
  --transparent-proxy-config -
```

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

### Policy TargetRef Example (MeshService)

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/005-policy-matching.md

Example of a policy's spec defining a TargetRef to a specific MeshService named 'backend'.

```yaml
type: UpstreamTimeout
mesh: mesh-1
name: timeouts
spec:
  targetRef:
    kind: MeshService
    name: backend
  to:
    # timeouts configuration
```

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

### Kubernetes Ingress Resource Example

Source: https://github.com/kumahq/kuma/blob/master/docs/proposals/dns-naming-compliance.md

An example of a Kubernetes Ingress resource used to expose services. Note the `serviceName` and `servicePort` fields.

```yaml
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: marketplace
  namespace: default
  annotations:
    kubernetes.io/ingress.class: kong
    kubernetes.io/ingress.global-static-ip-name: "kong-demo-ip"
spec:
  rules:
  - host: localhost
    http:
      paths:
      - path: /
        backend:
          serviceName: frontend
          servicePort: 80
```

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

### Build All Components

Source: https://github.com/kumahq/kuma/blob/master/CLAUDE.md

Builds all components of the Kuma project.

```bash
make build
```

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

### Inspect API Response Example (MeshTimeout)

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/066-policy-matching-with-real-resources.md

An example of the Inspect API response for a `MeshTimeout` policy, showcasing the `to` field with `targetRef` and `conf`.

```yaml
kind: MeshTimeout
metadata:
  name: mt-1
  namespace: client-ns
  labels:
    kuma.io/mesh: mesh-1
spec:
  to:
    - targetRef:
        kind: Mesh
      conf: conf1
    - targetRef:
        kind: MeshService
        name: backend
        namespace: finance
      conf: conf2
```

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

### Start K3d Cluster

Source: https://github.com/kumahq/kuma/blob/master/DEVELOPER.md

Initiates a k3d cluster, a prerequisite for Skaffold development.

```bash
make k3d/cluster/start
```

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

### Contextual Inbound Examples

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/084-finalized-schemes-for-unified-envoy-resources-and-stats-naming-formats.md

Examples of the contextual format for inbound resources, now including a scope token to distinguish between dataplane, ZoneIngress, and ZoneEgress.

```text
self_inbound_dp_httpport
self_inbound_dp_8080
self_inbound_zi_10001
self_inbound_ze_10001
```

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

### Structured Logging - Good Practice

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/003-logging.md

Use constant messages as the first argument to the logger and include dynamic values as key-value pairs for structured logging. This example demonstrates the correct way to log structured information.

```go
log.Info("dp connected", "name", dpName)
```

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

### Original Pod Manifest with Probes

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/049-grpc-tcp-probes.md

Example of a Kubernetes Pod manifest defining readiness, liveness, and startup probes using HTTP, gRPC, and TCP.

```yaml
apiVersion: v1
kind: Pod
metadata:
  name: busybox
  labels:
    run: busybox
  annotations:
    traffic.kuma.io/exclude-inbound-ports: "9800"
spec:
  containers:
    - name: busybox
      image: busybox
      readinessProbe:
        httpGet:
          path: /healthz
          port: 6851
        initialDelaySeconds: 3
        periodSeconds: 3
      livenessProbe:
        grpc:
          port: 6852
          service: liveness 
        initialDelaySeconds: 3
        periodSeconds: 3
      startupProbe:
        tcpSocket:
          port: 6853
        initialDelaySeconds: 3
        periodSeconds: 3

```

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

### Example Simplified Stat Name

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/078-migrating-to-consistent-and-well-defined-naming-for-non-system-envoy-resources-and-stats.md

This example shows a simplified format for stat names, contrasting with the full KRI resource name.

```plaintext
self_inbound_5050
```

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

### Example KRI with Collapsed Sections

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/078-migrating-to-consistent-and-well-defined-naming-for-non-system-envoy-resources-and-stats.md

This example demonstrates collapsing all KRI sections before `sectionName` into hyphens '-' to minimize metric cardinality.

```plaintext
kri_dp_-_-_-_-_5050
```

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

### Transparent Proxy Final Configuration Example

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/071-transparent-proxy-config-map-handling-outside-the-control-plane.md

This YAML output shows the merged configuration after applying multiple `--transparent-proxy-config` inputs, demonstrating precedence rules where STDIN input takes precedence.

```yaml
ipFamilyMode: ipv4
redirect:
  inbound:
    port: 1111
wait: 2
waitInterval: 3
```

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

### MeshExternalService Example

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/052-meshexternalservice-api.md

An example of a MeshExternalService resource. This resource specifies the type, destinations, and labels that can be used by a HostnameGenerator to create a corresponding hostname.

```yaml
kind: MeshExternalService
metadata:
  name: mydomain
  namespace: kuma-system
  labels:
    my.label.io/service: my-service 
    kuma.io/mesh: default
    kuma.io/zone: east-1
    kuma.io/origin: zone
spec:
  type: Managed # Managed|Passthrough|Extension
  destinations:
  - address: 192.168.0.1
    port: 9090 
...
```

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

### Run kumactl container image from 2.3.x onwards

Source: https://github.com/kumahq/kuma/blob/master/UPGRADE.md

Example of how to run the kumactl container image with version 2.3.0 or later, reflecting changes in image entrypoint.

```sh
docker run kumahq/kumactl:2.3.0 install transparent-proxy --help
```

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

### MeshHTTPRoute Example for MeshGateway

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/045-meshhttproute-meshgateway.md

This example demonstrates how to configure MeshHTTPRoute to route traffic for a specific hostname to a backend service via a MeshGateway.

```yaml
apiVersion: kuma.io/v1alpha1
kind: MeshHTTPRoute
metadata:
  name: edge-routes
spec:
  targetRef:
    kind: MeshGateway
    name: edge-gateway
  to:
  - targetRef:
      kind: Mesh
    hostnames:
    - example.com
    rules:
    - matches:
      - path:
          type: PathPrefix
          value: /
      default:
        backendRefs:
        - kind: MeshService
          name: backend_demo_svc_8080

```

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

### Install Kuma with Transparent Proxy Engine v1 legacy enabled via kumactl

Source: https://github.com/kumahq/kuma/blob/master/UPGRADE.md

This command installs Kuma using `kumactl`, specifying the legacy Transparent Proxy Engine v1 to be enabled. It pipes the output to `kubectl apply` for deployment.

```sh
kumactl install control-plane --set "legacy.transparentProxy=true" | kubectl apply -f-
```

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

### ProxyTemplate Configuration Example

Source: https://github.com/kumahq/kuma/blob/master/docs/proposals/proxy-template-redesign.md

This example demonstrates the structure of a ProxyTemplate policy, including imports and various modification operations for Envoy resources like clusters, listeners, routes, virtual hosts, HTTP filters, and network filters. Use 'add', 'remove', or 'patch' for top-level resources and 'addBefore', 'addAfter', 'addFirst', 'addLast', 'remove', or 'patch' for filters, considering the 'match' criteria for precise targeting.

```yaml
type: ProxyTemplate
mesh: default
name: custom-template-1
selectors:
  - match:
      service: backend
conf:
  imports:
    - default-proxy
  modifications:
    - cluster:
        match: # optional
          side: inbound # optional
          name: backend # optional
        operation: add # remove / patch
        value: # Envoy YAML
    - listener:
        match: # optional
          side: inbound # optional
          name: xyz # optional
        operation: add # remove / patch
        value: # Envoy YAML
    - route:
        match: # optional
          side: inbound # optional
          name: xyz # optional
        operation: add # remove / patch
        value: # Envoy YAML
    - virtualHost:
        match: # optional
          side: inbound # optional
          name: xyz # optional
        operation: add # remove / patch
        value: # Envoy YAML
    - httpFilter:
        match:
          side: inbound # optional
          type: envoy.filters.http.buffer
          listenerName: outbound:127.0.0.1:3000 # optional
        operation: addBefore # addAfter / addFirst / addLast / remove / patch
        value: # YAML of filter
    - networkFilter:
        operation: addAfter # addAfter / addFirst / addLast / remove / patch
        match:
          side: inbound # optional
          type: envoy.filters.network.rbac
          listenerName: inbound:127.0.0.1:1234 # optional
        value: # YAML of filter

```

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

### Logging INFO Level Examples

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/003-logging.md

Illustrates the correct and incorrect ways to log messages at the INFO level. Use human-readable messages that describe significant events.

```go
log.Info("proxy reconfigured", ...)
```

```go
log.Info("OnStreamResponse", ...)
```

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

### MeshZoneAddress Kubernetes Resource Example

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/096-ingress-address-sync.md

An example of a MeshZoneAddress resource in Kubernetes YAML format. This resource specifies the address and port of a zone ingress.

```yaml
apiVersion: kuma.io/v1alpha1
kind: MeshZoneAddress
metadata:
  name: zone-ingress-service-name # name of the service
  namespace: kuma-system # namespace of the service
  labels:
    kuma.io/mesh: default
    kuma.io/zone: zone-name
spec:
  address: 192.168.0.1 # string field, can support either IPv4 or IPv6
  port: 10001
```

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

### Start Kubernetes Cluster for E2E Tests

Source: https://github.com/kumahq/kuma/blob/master/DEVELOPER.md

Initiates the Kubernetes cluster required for running end-to-end tests. This command sets up the necessary infrastructure.

```bash
make test/e2e/k8s/start
```

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

### Policy Outbound Configuration Example (to array)

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/005-policy-matching.md

Demonstrates configuring outbound traffic policies using the 'to' array. Each entry can specify a target resource and its default configuration.

```yaml
type: UpstreamTimeout
mesh: mesh-1
name: timeouts
spec:
  targetRef:
    kind: MeshService
    name: backend
  to:
    - targetRef:
        kind: MeshService
        name: payments
      default:
        connectTimeout: 10s
    - targetRef:
        kind: MeshService
        name: web-api
      default:
        connectTimeout: 20s
```

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

### KRI Format Examples

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/084-finalized-schemes-for-unified-envoy-resources-and-stats-naming-formats.md

Examples of the KRI format used for user-facing Kuma resources like MeshService, MeshExternalService, MeshHTTPRoute, ZoneIngress, and ZoneEgress.

```text
kri_msvc_mesh-1_us-east-2_kuma-demo_backend_httpport
kri_extsvc_mesh-1__kuma-system_es1_
kri_mhttpr_mesh-1_us-east-2_kuma-demo_route-1_
kri_zi__us-east-2_kuma-system_zi1_
kri_ze__us-east-2_kuma-system_ze1_
```

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

### Example User Resource Name

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/077-naming-system-envoy-resources.md

Illustrates a naming convention for user-facing Envoy resources derived from Kuma resources.

```text
kri_msvc_mesh-1_us-east-2_kuma-demo_backend_httpport
```

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

### Complete MeshFaultInjection Resource Example

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/019-fault-injection-policy.md

A comprehensive example of a MeshFaultInjection resource, illustrating the structure for defining fault injection rules for both 'to' and 'from' sections, including specific target references and default HTTP configurations.

```yaml
type: MeshFaultInjection
mesh: example
name: example-fault-injection
spec:
 targetRef:
   kind: Mesh|MeshSubset|MeshService|MeshServiceSubset|MeshGatewayRoute
   name: example-fault-injection
 to:
   - targetRef:
       kind: Mesh|MeshSubset|MeshService|MeshServiceSubset
       name: backend
       mesh: example
     default:
       http:
        - abort:
            httpStatus: 500
            percentage: 50
        - delay:
            percentage: 50.5
            value: 5s
        - responseBandwidth:
            limit: 50 mbps
            percentage: 50
 from:
   - targetRef:
       kind: Mesh|MeshSubset|MeshService|MeshServiceSubset
       name: backend
       mesh: example
     default:
       http:
        - abort:
            httpStatus: 500
            percentage: 50
        - delay:
            percentage: 50.5
            value: 5s
        - responseBandwidth:
            limit: 50 mbps
            percentage: 50
```

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

### MeshTCPRoute Example for MeshGateway

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/045-meshhttproute-meshgateway.md

This example shows a MeshTCPRoute configuration for a MeshGateway, routing traffic to a specific subset of a backend service with weighted routing.

```yaml
apiVersion: kuma.io/v1alpha1
kind: MeshTCPRoute
metadata:
  name: edge-routes
spec:
  targetRef:
    kind: MeshGateway
    name: edge-gateway
  to:
  - targetRef:
      kind: Mesh
    rules:
      - default:
          backendRefs:
            - kind: MeshServiceSubset
              name: backend_kuma-demo_svc_3001
              tags:
                version: "1.0"
              weight: 90
            - kind: MeshServiceSubset
              name: backend_kuma-demo_svc_3001
              tags:
                version: "2.0"
              weight: 10

```

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

### Build All Binaries

Source: https://github.com/kumahq/kuma/blob/master/DEVELOPER.md

Compiles all the necessary binaries for the project.

```bash
make build
```

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

### Clear Mise Cache and Remove Kubectl Installs

Source: https://github.com/kumahq/kuma/blob/master/DEVELOPER.md

Use this command to clear the mise cache and remove specific kubectl installations, useful for troubleshooting.

```bash
mise cache clear
rm -rf ~/.local/share/mise/{installs,plugins}/kubectl
```

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

### Raw List of Rules Example

Source: https://github.com/kumahq/kuma/blob/master/docs/madr/decisions/005-policy-matching.md

Illustrates the raw 'from' array format in a Kuma policy, showing multiple entries with specific target references and default configurations.

```yaml
from:
  - targetRef:
      kind: MeshSubset
      name: mesh-1
      tags:
        kuma.io/zone: us-east
      default:
        param1: value1
        param2: value2
  - targetRef:
      kind: MeshSubset
      name: mesh-1
      tags:
        team: dev
      default:
        param2: value3
        param3: value4
```

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

### Kubernetes ExternalName Service Example

Source: https://github.com/kumahq/kuma/blob/master/docs/proposals/dns-naming-compliance.md

An example of a Kubernetes Service of type `ExternalName` attempting to use a Kuma-generated DNS name. This demonstrates the naming conflict.

```yaml
apiVersion: v1
kind: Service
metadata:
  name: frontend
  namespace: default
  annotations:
    ingress.kubernetes.io/service-upstream: "true"
spec:
  type: ExternalName
  externalName: frontend_default_svc_80.mesh
```