Angie Ingress Controller

https://angie.software/anic/docs/
Admin
Angie Ingress Controller (ANIC) is a solution for managing traffic of containerized applications in...
Tokens:149,356
Snippets:704
Trust Score:9.3
Update:10 months ago
Show doc for...
Tokens:
Raw
### Full Example VirtualServer with OIDC Policy (YAML)

Source: https://angie.software/anic/docs/custom-resources/configuring-oidc

A complete Angie Software VirtualServer configuration demonstrating how to integrate the OIDC policy and define the necessary map variables for token validation. This setup routes traffic for `test.example.com` to `app-server-payload` and enables OIDC authentication.

```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
  name: test-echo
spec:
  host: test.example.com
  upstreams:
    - name: app-server-payload
      service: echoserver
      port: 8077
  routes:
    - path: /
      action:
        proxy:
          upstream: app-server-payload
      policies:
        - name: oidc-policy
  maps:
    - variable: $jwt_claim_iat
      source: $oidc_client
      parameters:
        - value: 'myclient'
          result: '80'
    - variable: $jwt_claim_iss
      source: $oidc_client
      parameters:
        - value: 'myclient'
          result: 'PROVIDER_URL'
    - variable: $jwt_claim_sub
      source: $oidc_client
      parameters:
        - value: 'myclient'
          result: 'myclient'
    - variable: $jwt_claim_aud
      source: $oidc_client
      parameters:
        - value: 'myclient'
          result: 'myclient'

```

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

### Full VirtualServer Configuration Example

Source: https://angie.software/anic/docs/custom-resources/configuring-oidc

An example of a complete VirtualServer configuration incorporating OIDC authentication and map definitions for JWT claim validation.

```APIDOC
## Full VirtualServer Configuration Example

This example demonstrates a complete `VirtualServer` configuration with OIDC authentication enabled and necessary JWT claim mappings.

```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
  name: test-echo
spec:
  host: test.example.com
  upstreams:
    - name: app-server-payload
      service: echoserver
      port: 8077
  routes:
    - path: /
      action:
        proxy:
          upstream: app-server-payload
      policies:
        - name: oidc-policy
  maps:
    - variable: $jwt_claim_iat
      source: $oidc_client
      parameters:
        - value: 'myclient'
          result: '80'
    - variable: $jwt_claim_iss
      source: $oidc_client
      parameters:
        - value: 'myclient'
          result: 'PROVIDER_URL'
    - variable: $jwt_claim_sub
      source: $oidc_client
      parameters:
        - value: 'myclient'
          result: 'myclient'
    - variable: $jwt_claim_aud
      source: $oidc_client
      parameters:
        - value: 'myclient'
          result: 'myclient'
```
```

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

### VirtualServer Configuration Example

Source: https://angie.software/anic/docs/configuration/virtualserver-and-virtualserverroute-resources

This is a comprehensive example of a VirtualServer configuration, demonstrating various settings such as host, TLS, static locations, upstream definitions, routing rules with conditions and actions, active health probes, OIDC token validation maps, and authentication request locations.

```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
  name: cafe
spec:
  host: cafe.example.com
  tls:
    secret: cafe-secret
  staticLocations:
  - type: root
    urlPath: /americano
    dirPath: /latte
  gunzip: on
  upstreams:
  - name: tea
    service: tea-svc
    port: 80
  - name: coffee
    service: coffee-svc
    port: 80
  routes:
    authRequest: /auth/p
    authRequestSets:
      - key: foo
        value: bar
    matches:
    - conditions:
      - variable: $request_method
        value: POST
      action:
        pass: tea-post
    action:
      pass: tea-post
  - path: /coffee
    action:
      pass: coffee
  - path: ~ ^/decaf/.*\.jpg$
    action:
      pass: coffee
  - path: = /green/tea
    action:
      pass: tea
  activeHealthProbes:
  - name: activename1
    upstream: tea
    uri: uri
    port:  80
    interval: 3s
    isEssential: true
    isPersistent: true
    maxBody: 10m
    fails: 4
    passes: 5
    mode: onfail
  maps:
  - variable: $jwt_claim_iat
    source: $oidc_client
    parameters:
      - value: 'myclient'
        result: '80'
  - variable: $jwt_claim_iss
    source: $oidc_client
    parameters:
      - value: 'myclient'
        result: 'PROVIDER_URL'
  - variable: $jwt_claim_sub
    source: $oidc_client
    parameters:
      - value: 'myclient'
        result: 'myclient'
  - variable: $jwt_claim_aud
    source: $oidc_client
    parameters:
      - value: 'myclient'
        result: 'myclient'
  authRequestLocations:
  - path: /auth/path
    proxyPass:
      upstreamName: "tea"
    proxyPassHeaders:
      - key: Content-Length
        value: "100"
```

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

### VirtualServer TLS Configuration Example

Source: https://angie.software/anic/docs/configuration/virtualserver-and-virtualserverroute-resources

Example demonstrating the TLS configuration for a VirtualServer, specifying the secret, redirection, and various SSL/TLS session parameters. This configuration is crucial for securing traffic and optimizing connection performance.

```yaml
secret: cafe-secret
redirect:
  enable: true
ssl_session_timeout: 1h
ssl_session_cache: shared:SSL:10m
ssl_session_tickets: on
ssl_stapling: on
ssl_stapling_verify: on
```

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

### Example Generated Angie Configuration Content

Source: https://angie.software/anic/docs/ingress-resources/mergeable-ingress-types

This is an example of the generated Angie configuration file. It shows the upstream blocks for the coffee and tea services, as well as the server block for handling HTTP and HTTPS traffic on port 80 and 443.

```nginx
upstream default-cafe-ingress-coffee-minion-cafe.example.com-coffee-svc {
    server 172.17.0.5:80;
    server 172.17.0.6:80;
}
upstream default-cafe-ingress-tea-minion-cafe.example.com-tea-svc {
    server 172.17.0.7:80;
    server 172.17.0.8:80;
    server 172.17.0.9:80;
}

server {
    listen 80;
    listen 443 ssl;

```

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

### Map Configuration for Variable Mapping

Source: https://angie.software/anic/docs/configuration/virtualserver-and-virtualserverroute-resources

Provides an example of including map variables based on input values such as `default`, `volatile`, `include`, and `hostnames`.

```APIDOC
## Maps Configuration Example#

### Description
Example of including map variables based on input values.

### Method
N/A (Configuration Structure)

### Endpoint
N/A (Configuration Structure)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
- **variable** (string) - Required - The variable to configure (e.g., `$result_var`).
- **source** (string) - Required - The source of the variable value (e.g., `$host`).
- **parameters** (object[]) - Required - A list of parameter mappings.
  - **value** (string) - Required - The input value for the mapping (e.g., 'default', 'volatile', 'include', 'example.com').
  - **result** (string) - Required - The resulting value for the variable based on the input `value`.

### Request Example
```yaml
maps:
  - variable: $result_var
    source: $host
    parameters:
      - value: 'default'
        result: 'default_value'
      - value: 'volatile'
        result: ''
      - value: 'include'
        result: '/dev/stdout'
      - value: 'example.com'
        result: '1'
      - value: '*.example.com'
        result: '1'
```

### Response
N/A (Configuration Structure)

### Response Example
N/A (Configuration Structure)
```

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

### Website Configuration API

Source: https://angie.software/anic/docs/installation/install

This section details the configuration for website routing, including URL definitions, conditions for rule matching, and split actions for traffic management.

```APIDOC
## Website Configuration

### Description
Configuration schema for website routing, encompassing URL definitions, conditional matching rules, and traffic splitting logic with proxy actions.

### Method
N/A (Configuration Schema)

### Endpoint
N/A (Configuration Schema)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **url** (string) - The URL configuration for the website.
- **return** (object) - Defines the return object for an action.
  - **description** (string) - Description of the return object.
  - **type** (string) - Type of the return object.
  - **properties** (object) - Properties of the return object.
    - **body** (string) - The body of the return object.
    - **code** (integer) - The status code of the return object.
    - **type** (string) - The type of the return object.
- **conditions** (array) - An array of conditions for matching rules.
  - **items** (object) - Defines a condition for a MatchRule.
    - **description** (string) - Description of the condition.
    - **type** (string) - Type of the condition.
    - **properties** (object) - Properties of the condition.
      - **argument** (string) - The argument for the condition.
      - **cookie** (string) - The cookie to check for the condition.
      - **header** (string) - The header to check for the condition.
      - **value** (string) - The value to compare against.
      - **variable** (string) - The variable to use in the condition.
- **splits** (array) - An array of split configurations for traffic management.
  - **items** (object) - Defines a split.
    - **description** (string) - Description of the split.
    - **type** (string) - Type of the split.
    - **properties** (object) - Properties of the split.
      - **action** (object) - Defines the action to take for this split.
        - **description** (string) - Description of the action.
        - **type** (string) - Type of the action.
        - **properties** (object) - Properties of the action.
          - **pass** (string) - The value to pass for this action.
          - **proxy** (object) - Defines proxy settings for the action.
            - **description** (string) - Description of the proxy action.
            - **type** (string) - Type of the proxy action.
            - **properties** (object) - Properties of the proxy action.
              - **requestHeaders** (object) - Defines request header manipulation for the proxy.
                - **description** (string) - Description of request header manipulation.
                - **type** (string) - Type of request header manipulation.
                - **properties** (object) - Properties of request header manipulation.
                  - **pass** (boolean) - Whether to pass through request headers.
                  - **set** (array) - Headers to set in the request.
                    - **items** (object) - Defines an HTTP Header.
                      - **description** (string) - Description of the header.
                      - **type** (string) - Type of the header.
                      - **properties** (object) - Properties of the header.
                        - **name** (string) - The name of the header.
                        - **value** (string) - The value of the header.
              - **responseHeaders** (object) - Defines response header manipulation for the proxy.
                - **description** (string) - Description of response header manipulation.
                - **type** (string) - Type of response header manipulation.
                - **properties** (object) - Properties of response header manipulation.
                  - **add** (array) - Headers to add to the response.
                    - **items** (object) - Defines an HTTP Header with an optional 'always' field.
                      - **description** (string) - Description of the added header.
                      - **type** (string) - Type of the added header.
                      - **properties** (object) - Properties of the added header.
                        - **always** (boolean) - Whether to always add the header.
                        - **name** (string) - The name of the header.
                        - **value** (string) - The value of the header.
                  - **hide** (array) - Headers to hide from the response.
                    - **items** (string) - The name of the header to hide.
                  - **ignore** (array) - Headers to ignore in the response.
                    - **items** (string) - The name of the header to ignore.
                  - **pass** (array) - Headers to pass through in the response.
                    - **items** (string) - The name of the header to pass through.

### Request Example
```json
{
  "url": "/example.com",
  "return": {
    "description": "Returns a string",
    "type": "string",
    "properties": {
      "body": "Success",
      "code": 200,
      "type": "application/json"
    }
  },
  "conditions": [
    {
      "argument": "",
      "cookie": "",
      "header": "User-Agent",
      "value": "Mobile",
      "variable": "$http_user_agent"
    }
  ],
  "splits": [
    {
      "action": {
        "pass": "http://example.net",
        "proxy": {
          "requestHeaders": {
            "pass": true,
            "set": [
              {
                "name": "X-Custom-Header",
                "value": "CustomValue"
              }
            ]
          },
          "responseHeaders": {
            "add": [
              {
                "always": false,
                "name": "X-Response-Header",
                "value": "ResponseValue"
              }
            ],
            "hide": [
              "X-Internal-Header"
            ],
            "ignore": [
              "ETag"
            ],
            "pass": [
              "Content-Type"
            ]
          }
        }
      }
    }
  ]
}
```

### Response
#### Success Response (200)
N/A (Configuration Schema)

#### Response Example
N/A (Configuration Schema)
```

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

### Action Return Configuration

Source: https://angie.software/anic/docs/installation/install

Configures a return action for a route, allowing a custom response body and status code.

```APIDOC
## Action Return

### Description
Configures a return action for a route, allowing a custom response body and status code.

### Parameters
#### Request Body
- **action.return.body** (string) - Optional - The custom response body.
- **action.return.code** (integer) - Optional - The HTTP status code for the response (defaults to 200).
- **action.return.type** (string) - Optional - The content type of the response body (e.g., 'text/plain', 'application/json').

### Request Example
```json
{
  "action": {
    "return": {
      "code": 201,
      "type": "application/json",
      "body": "{\"message\": \"Created successfully\"}"
    }
  }
}
```

### Response
#### Success Response (200)
- **action.return.body** (string) - The custom response body.
- **action.return.code** (integer) - The HTTP status code for the response.
- **action.return.type** (string) - The content type of the response body.

#### Response Example
```json
{
  "action": {
    "return": {
      "code": 201,
      "type": "application/json",
      "body": "{\"message\": \"Created successfully\"}"
    }
  }
}
```
```

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

### Configure JWT Authentication with JWKS using VirtualServer and Policy

Source: https://angie.software/anic/docs/custom-resources/jwks

This example demonstrates deploying a web application, configuring load balancing with VirtualServer, and applying a JWT policy. It highlights the use of JwksURI for external identity providers like Keycloak, differentiating it from a direct JWT example.

```yaml
# VirtualServer configuration example
apiVersion: appprotect.f5.com/v1
kind: VirtualServer
metadata:
  name: webapp-vs
spec:
  host: webapp.example.com
  upstreams:
  - name: webapp
    service: webapp-service
    port: 80
  policies:
  - name: jwt-policy

---

# Policy configuration example for JWKS
apiVersion: appprotect.f5.com/v1
kind: Policy
metadata:
  name: jwt-policy
spec:
  jwt:
    jwksURI: http://keycloak.example.com/realms/myrealm/protocol/openid-connect/certs
    # Other JWT policy configurations...
```

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

### OpenID Connect Authentication Setup

Source: https://angie.software/anic/docs/custom-resources/configuring-oidc

Detailed steps to configure OIDC authentication, including command-line arguments, secret creation, policy definition, and map configurations for JWT claim validation.

```APIDOC
## OpenID Connect Authentication Setup

To configure authentication via OpenID Connect, follow these steps:

1.  **Enable OIDC:** Set the command-line argument `enable-oidc=true`.
    The following modules will be loaded:
    * `load_module modules/ngx_http_js_module.so;`
    * `load_module modules/ngx_http_auth_jwt_module.so;`
    * `load_module modules/ngx_http_keyval_module.so;`

2.  **Create Client Secret:** Add a secret with the client key, encoded in Base64.
    ```yaml
    apiVersion: v1
    kind: Secret
    metadata:
      name: oidc-secret
    type: angie.software/oidc
    data:
      client-secret: <angie__client_secret>
    ```
    Apply the secret:
    ```bash
    kubectl apply -f oidc/client-secret.yaml
    ```

3.  **Define OIDC Policy:** Create a policy resource for OIDC.
    ```yaml
    apiVersion: k8s.angie.software/v1
    kind: Policy
    metadata:
      name: oidc-policy
    spec:
       oidc:
         clientID: myclient
         clientSecret: oidc-secret
         authEndpoint: https://idp.example.com/openid-connect/auth
         jwksURI: https://idp.example.com/openid-connect/certs
         tokenEndpoint: https://idp.example.com/openid-connect/token
         scope: openid+profile+email
         accessTokenEnable: true
    ```
    Apply the policy:
    ```bash
    kubectl apply -f oidc/oidc.yaml
    ```

4.  **Apply Policy to Server/Route:** Reference the policy in your server or route configuration.
    ```yaml
    policies:
      - name: oidc-policy
    ```

5.  **Map JWT Claims:** Define mandatory variables for token validation in the `maps` section of your VirtualServer specification.
    ```yaml
    maps:
      - variable: $jwt_claim_iat
        source: $oidc_client
        parameters:
          - value: 'myclient'
            result: '80'
      - variable: $jwt_claim_iss
        source: $oidc_client
        parameters:
          - value: 'myclient'
            result: 'PROVIDER_URL'
      - variable: $jwt_claim_sub
        source: $oidc_client
        parameters:
          - value: 'myclient'
            result: 'myclient'
      - variable: $jwt_claim_aud
        source: $oidc_client
        parameters:
          - value: 'myclient'
            result: 'myclient'
    ```
    This will add the following directives to the VirtualServer configuration:
    ```nginx
    map $oidc_client $jwt_claim_iat {
        myclient 80;
    }

    map $oidc_client $jwt_claim_iss {
        myclient PROVIDER_URL;
    }

    map $oidc_client $jwt_claim_sub {
        myclient myclient;
    }

    map $oidc_client $jwt_claim_aud {
        myclient myclient;
    }
    ```
```

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

### Website Configuration Properties

Source: https://angie.software/anic/docs/installation/install

Defines the top-level properties for a website configuration, including its name and namespace.

```APIDOC
## Website Configuration

### Description
Defines the basic properties of a website configuration.

### Parameters
#### Request Body
- **name** (string) - Required - The name of the website.
- **namespace** (string) - Required - The namespace for the website.

### Request Example
```json
{
  "name": "example.com",
  "namespace": "default"
}
```

### Response
#### Success Response (200)
- **name** (string) - The name of the website.
- **namespace** (string) - The namespace for the website.

#### Response Example
```json
{
  "name": "example.com",
  "namespace": "default"
}
```
```

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

### Configure VirtualServer with HTTP and Server Snippets

Source: https://angie.software/anic/docs/configuration/virtualserver-and-virtualserverroute-resources

This example demonstrates how to configure a VirtualServer resource in Angie using `http-snippets` for request limiting and `server-snippets` for general server configurations. It requires the `k8s.angie.software/v1` API version and defines upstreams and routes.

```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
  name: cafe
  namespace: cafe
spec:
  http-snippets: |
    limit_req_zone $binary_remote_addr zone=mylimit:10m rate=1r/s;
    proxy_cache_path /tmp keys_zone=one:10m;
  host: cafe.example.com
  tls:
    secret: cafe-secret
  server-snippets: |
    limit_req zone=mylimit burst=20;
  upstreams:
    - name: tea
      service: tea-svc
      port: 80
    - name: coffee
      service: coffee-svc
      port: 80
  routes:
    - path: /tea
      location-snippets: |
        proxy\_cache one;
        proxy\_cache\_valid 200 10m;
      action:
        pass: tea
    - path: /coffee
      action:
        pass: coffee

```

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

### Action Proxy Configuration

Source: https://angie.software/anic/docs/installation/install

Configures the proxy action for a route, allowing manipulation of request and response headers.

```APIDOC
## Action Proxy

### Description
Configures the proxy behavior for a route, including upstream service and header manipulation.

### Parameters
#### Request Body
- **proxy.requestHeaders** (object) - Optional - Configuration for manipulating request headers.
- **proxy.responseHeaders** (object) - Optional - Configuration for manipulating response headers.
- **proxy.rewritePath** (string) - Optional - Path to rewrite before proxying.
- **proxy.upstream** (string) - Required - The upstream service URL.

### Request Example
```json
{
  "action": {
    "proxy": {
      "upstream": "http://api.example.com/v1",
      "requestHeaders": {
        "pass": true,
        "set": [
          {"name": "X-Custom-Header", "value": "my-value"}
        ]
      },
      "responseHeaders": {
        "hide": ["X-Internal-Info"]
      },
      "rewritePath": "/newpath"
    }
  }
}
```

### Response
#### Success Response (200)
- **action.proxy.requestHeaders** (object) - Request header manipulation settings.
- **action.proxy.responseHeaders** (object) - Response header manipulation settings.
- **action.proxy.rewritePath** (string) - The rewritten path.
- **action.proxy.upstream** (string) - The upstream service URL.

#### Response Example
```json
{
  "action": {
    "proxy": {
      "upstream": "http://api.example.com/v1",
      "requestHeaders": {
        "pass": true,
        "set": [
          {"name": "X-Custom-Header", "value": "my-value"}
        ]
      },
      "responseHeaders": {
        "hide": ["X-Internal-Info"]
      },
      "rewritePath": "/newpath"
    }
  }
}
```
```

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

### RateLimit Policy Configuration

Source: https://angie.software/anic/docs/installation/install

Defines a rate limit policy with parameters like burst, delay, rate, and logging level.

```yaml
rateLimit:
  description: RateLimit defines a rate limit policy.
  type: object
  properties:
    burst:
      type: integer
    delay:
      type: integer
    dryRun:
      type: boolean
    key:
      type: string
    logLevel:
      type: string
    noDelay:
      type: boolean
    rate:
      type: string
    rejectCode:
      type: integer
    zoneSize:
      type: string
```

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

### Angie Ingress Controller Docker Images

Source: https://angie.software/anic/docs/installation/install

Lists available Docker images for the Angie Ingress Controller. Users should pull the image corresponding to their desired version and base OS.

```text
anic.docker.angie.software/anic:0.7.2-alpine
anic.docker.angie.software/anic:0.7.2-debian
anic.docker.angie.software/anic:0.7.2-altlinux
```

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

### Deploy cert-manager and Self-Signed CA using kubectl

Source: https://angie.software/anic/docs/custom-resources/certmanager

Deploys cert-manager and its dependencies using a provided URL. This command installs the cert-manager controller and related components.

```bash
kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.8.0/cert-manager.yaml
```

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

### Create ConfigMap for Angie PRO Settings

Source: https://angie.software/anic/docs/installation/install

Applies a Kubernetes ConfigMap to store configuration settings for Angie PRO. This allows for externalizing and managing Angie's operational parameters.

```yaml
kind: ConfigMap
apiVersion: v1
metadata:
  name: angie-config
  namespace: angie-ingress
data:
```

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

### GlobalConfiguration for Load Balancing (Kubernetes)

Source: https://angie.software/anic/docs/installation/install

Applies a Custom Resource Definition for GlobalConfiguration to manage load balancing for TCP and UDP connections using Kubernetes.

```yaml
apiVersion: apiextensions.k8s.io/v1
kind: CustomResourceDefinition
metadata:
  annotations:
    controller-gen.kubebuilder.io/version: v0.11.3
  creationTimestamp: null
  name: globalconfigurations.k8s.angie.software
spec:
  group: k8s.angie.software
  names:
    kind: GlobalConfiguration
    listKind: GlobalConfigurationList
    plural: globalconfigurations
    shortNames:
      - gc
    singular: globalconfiguration
  scope: Namespaced
  versions:
    - name: v1alpha1
      schema:
        openAPIV3Schema:
          description: GlobalConfiguration defines the GlobalConfiguration resource.
          type: object
          properties:
            apiVersion:
              description: 'APIVersion defines the versioned schema of this representation of an object. Servers should convert recognized schemas to the latest internal value, and may reject unrecognized values. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources'
              type: string
            kind:
              description: 'Kind is a string value representing the REST resource this object represents. Servers may infer this from the endpoint the client submits requests to. Cannot be updated. In CamelCase. More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds'
              type: string
            metadata:
              type: object
            spec:
              description: GlobalConfigurationSpec is the spec of the GlobalConfiguration resource.
              type: object
              properties:
                listeners:
                  type: array
                  items:
                    description: Listener defines a listener.
                    type: object
                    properties:
                      name:
                        type: string
                      port:
                        type: integer
                      protocol:
                        type: string
      served: true
      storage: true
```

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

### Listener Configuration Example (Kubernetes YAML)

Source: https://angie.software/anic/docs/configuration/globalconfiguration-resource

This snippet illustrates the configuration of a single listener within the GlobalConfiguration resource. It specifies the listener's name, port, and protocol (TCP in this case).

```yaml
name: dns-tcp
port: 5353
protocol: TCP

```

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

### Viewing VirtualServer Resource Status with kubectl

Source: https://angie.software/anic/docs/logging-and-monitoring/reporting-resources-status

Shows how to retrieve the status of VirtualServer resources using `kubectl get virtualservers`. The output includes the resource name, state, host, IP address, ports, and age. An example using `-o wide` is provided to display the external host name.

```bash
$ kubectl get virtualservers

    NAME   STATE   HOST                   IP            PORTS      AGE
    myapp  Valid   myapp.example.com      12.13.23.123  [80,443]   34s


```

```bash
$ kubectl get virtualservers -o wide

    NAME   STATE   HOST               IP    EXTERNALHOSTNAME                                                         PORTS      AGE
    mysite Valid   mysite.example.com       ae430f41a1a0042908655abcdefghijkl-12345678.eu-west-2.elb.amazonaws.com   [80,443]   106s


```

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

### Configure TLS Passthrough with TransportServer in Kubernetes

Source: https://angie.software/anic/docs/custom-resources/tls-passthrough

Example of using a TransportServer resource to configure TLS Passthrough load balancing. This setup directs TLS traffic to a backend application without ANIC decrypting it, using SNI for routing. It requires ANIC to be enabled with custom resources and TLS passthrough support.

```yaml
apiVersion: k8s.angie.dev/v1alpha1
kind: TransportServer
metadata:
  name: secure-app-passthrough
spec:
  entryPoint: transport-tls
  virtualServerPort: 8443
  destination:
    host: app.example.com
    port: 8443
  tls:
    mode: Passthrough

```

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

### Create VirtualServer Resource

Source: https://angie.software/anic/docs/custom-resources/basic_authentication

This section demonstrates creating a `VirtualServer` resource that applies the `basic-auth-policy` to incoming requests for `cafe.example.com`.

```APIDOC
## Create VirtualServer Resource

### Description
Define a `VirtualServer` resource for `cafe.example.com`. This configuration routes requests for `/tea` to the `tea` upstream and requests for `/coffee` to the `coffee` upstream. Crucially, it applies the `basic-auth-policy` to enforce authentication for all traffic handled by this VirtualServer.

### Method
`kubectl apply -f <filename>.yaml`

### Endpoint
N/A

### Parameters
N/A

### Request Example
```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
  name: cafe
spec:
  host: cafe.example.com
  policies:
  - name: basic-auth-policy
  upstreams:
  - name: tea
    service: tea-svc
    port: 80
  - name: coffee
    service: coffee-svc
    port: 80
  routes:
  - path: /tea
    action:
      pass: tea
  - path: /coffee
    action:
      pass: coffee
```

### Response
N/A
```

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

### Подключение к Kubernetes-кластеру

Source: https://angie.software/anic/docs/installation/installation-in-YC

Получение учетных данных для подключения к Kubernetes-кластеру Яндекс.Облака и их применение. Используется для управления кластером с помощью kubectl.

```bash
yc managed-kubernetes cluster get-credentials otus --external

```

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

### Install cert-manager

Source: https://angie.software/anic/docs/installation/installation-in-YC

Installs cert-manager, a Kubernetes add-on to automate the management and issuance of TLS certificates. Tested with version 1.12.1. Requires kubectl.

```bash
$ kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.12.1/cert-manager.yaml

```

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

### VirtualServer Configuration (Kubernetes)

Source: https://angie.software/anic/docs/custom-resources/basic_authentication

This Kubernetes VirtualServer resource defines how incoming traffic to 'cafe.example.com' is routed. It applies the 'basic-auth-policy' and directs traffic to 'tea' or 'coffee' upstreams based on the path.

```yaml
apiVersion: k8s.angie.software/v1
kind: VirtualServer
metadata:
  name: cafe
spec:
  host: cafe.example.com
  policies:
  - name: basic-auth-policy
  upstreams:
  - name: tea
    service: tea-svc
    port: 80
  - name: coffee
    service: coffee-svc
    port: 80
  routes:
  - path: /tea
    action:
      pass: tea
  - path: /coffee
    action:
      pass: coffee

```

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

### Обновление Helm чарта с выключенным GlobalConfiguration

Source: https://angie.software/anic/docs/installation/installation-in-YC

Эта команда `helm upgrade` обновляет развертывание ANIC, используя текущие настройки. В данном случае, она применяется после установки чарта с `globalConfiguration.create: false`, подготавливая к следующему шагу.

```bash
$ helm upgrade anic .

```

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

### ANIC Template Error Example (Log)

Source: https://angie.software/anic/docs/shared-examples/custom-templates

This example demonstrates the log output when an invalid custom template is detected by ANIC during startup. It indicates a template parsing error, specifically an 'unexpected EOF'.

```text
Error updating Angie main template: template: angieTemplate:98: unexpected EOF

```

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

### Создание Kubernetes-секрета для доступа к образам

Source: https://angie.software/anic/docs/installation/installation-with-helm

Команда для создания Kubernetes-секрета 'regcred' с использованием файла Docker-конфигурации. Этот секрет используется для доступа к приватным образам в Kubernetes.

```bash
$ kubectl create secret generic regcred \
      --from-file=.dockerconfigjson=$HOME/.docker/config.json \
      --type=kubernetes.io/dockerconfigjson

```

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

### Ingress MTLS Configuration Example

Source: https://angie.software/anic/docs/custom-resources/ingress-mtls

This section provides an example of deploying a web application and configuring load balancing using VirtualServer with the Ingress MTLS policy. It also mentions the support for Certificate Revocation Lists (CRL).

```APIDOC
## Ingress MTLS Configuration

### Description
This documentation outlines the steps to deploy a web application, configure load balancing using VirtualServer, and apply the Ingress MTLS policy. It highlights the support for Certificate Revocation Lists (CRL) for enhanced security.

### Method
N/A (Configuration guide)

### Endpoint
N/A (Configuration guide)

### Parameters
#### Path Parameters
N/A

#### Query Parameters
N/A

#### Request Body
N/A

### Request Example
N/A (Configuration guide)

### Response
#### Success Response (200)
N/A (Configuration guide)

#### Response Example
N/A (Configuration guide)

### Prerequisites

1.  **Install ANIC**: Ensure the Angie Ingress Controller is installed.
2.  **Set ANIC Public IP**: Store the public IP address of ANIC in an environment variable.
    ```bash
    $ IC_IP=<your_ip_address>
    ```
3.  **Set ANIC HTTPS Port**: Store the HTTPS port of ANIC in an environment variable.
    ```bash
    $ IC_HTTPS_PORT=<port_number>
    ```

### Related Information
-   **Certificate Revocation Lists (CRL)**: Refer to 'Using a Certificate Revocation List' for details on CRL configuration.
```

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

### Установка HTTP-порта ANIC

Source: https://angie.software/anic/docs/ingress-resources/complete-example

Эта команда сохраняет HTTP-порт ANIC в переменной оболочки. Эта переменная необходима для настройки сетевых служб.

```bash
$ IC_HTTP_PORT=<номер_порта>
```

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

### Policy Resource Example: Access Control Allow

Source: https://angie.software/anic/docs/configuration/policy-resource

This YAML example defines a Kubernetes Policy resource that configures access control to allow incoming requests only from the '10.0.0.0/8' subnet. It demonstrates the basic structure of a Policy resource and its 'accessControl' field.

```yaml
apiVersion: k8s.angie.software/v1
kind: Policy
metadata:
  name: allow-localhost
spec:
  accessControl:
    allow:
    - 10.0.0.0/8

```

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

### Kubernetes ConfigMap Event with Error Example

Source: https://angie.software/anic/docs/shared-examples/custom-templates

This is an example of Kubernetes events for a ConfigMap, showing both successful updates and updates that failed due to errors. Specifically, it highlights a 'Warning' event indicating that configuration was updated but not applied because of an error in parsing the main template.

```text
Events:
  Type     Reason            Age                From      Message
  ----     ------            ----               ----      -------
  Normal   Updated           12s (x2 over 25s)  anic      Configuration from anic/angie-config was updated
  Warning  UpdatedWithError  10s                anic      Configuration from anic/angie-config was updated, but not applied: Error when parsing the main template: template: angieTemplate:98: unexpected EOF
  Warning  UpdatedWithError  8s                 anic      Configuration from anic/angie-config was updated, but not applied: Error when writing main Config

```

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

### Action Redirect Configuration

Source: https://angie.software/anic/docs/installation/install

Configures a redirect action for a route, specifying the redirect code and URL.

```APIDOC
## Action Redirect

### Description
Configures a redirect action for a route, specifying the HTTP status code and the target URL.

### Parameters
#### Request Body
- **action.redirect.code** (integer) - Required - The HTTP status code for the redirect (e.g., 301, 302).
- **action.redirect.url** (string) - Required - The URL to redirect to.

### Request Example
```json
{
  "action": {
    "redirect": {
      "code": 302,
      "url": "https://newdomain.com/newpage"
    }
  }
}
```

### Response
#### Success Response (200)
- **action.redirect.code** (integer) - The HTTP status code for the redirect.
- **action.redirect.url** (string) - The URL to redirect to.

#### Response Example
```json
{
  "action": {
    "redirect": {
      "code": 302,
      "url": "https://newdomain.com/newpage"
    }
  }
}
```
```

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

### Apply Kubernetes Configurations

Source: https://angie.software/anic/docs/custom-resources/basic_authentication

This command applies the Kubernetes configurations defined in the 'cafe.yaml' file to the cluster. It ensures that the Deployments and Services for the 'coffee' and 'tea' applications are created and running.

```bash
$ kubectl apply -f cafe.yaml

```

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

### Включение GlobalConfiguration и добавление TCP-прослушивателя в values.yaml для ANIC

Source: https://angie.software/anic/docs/installation/installation-in-YC

Этот YAML-фрагмент демонстрирует, как включить `globalConfiguration` и определить TCP-прослушиватель для MySQL. После включения `create: true`, указывается `spec` с `listeners`, где задается имя, порт и протокол для MySQL-TCP.

```yaml
globalConfiguration:
  ## Creates the GlobalConfiguration custom resource. Requires controller.enableCustomResources.
  create: true

  ## The spec of the GlobalConfiguration for defining the global configuration parameters of the Ingress Controller.
  spec:
    listeners:
    # - name: dns-udp
    #   port: 5353
    #   protocol: UDP
    - name: mysql-tcp
      port: 13306
      protocol: TCP

```

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

### JWT Authentication Configuration

Source: https://angie.software/anic/docs/installation/install

Holds JWT authentication configuration including realm, secret, and token details.

```yaml
jwt:
  description: JWT holds JWT authentication configuration.
  realm: string
  secret: string
  token: string
```

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

### Kubernetes Command Line Operations

Source: https://angie.software/anic/docs/custom-resources/advanced-routing

Provides commands to apply Kubernetes configurations and inspect resources. Includes applying YAML files and describing VirtualServer events.

```bash
$ kubectl create -f cafe.yaml

$ kubectl create -f cafe-virtual-server.yaml

$ kubectl describe virtualserver cafe

```

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

### Route Definition

Source: https://angie.software/anic/docs/installation/install

Defines a route within a website configuration, specifying actions, error pages, and DoS protection.

```APIDOC
## Route

### Description
Defines a route for handling specific requests, including actions, error pages, and DoS settings.

### Parameters
#### Request Body
- **action** (object) - Optional - Defines the action to perform for this route.
- **dos** (string) - Optional - Specifies Denial-of-Service protection settings.
- **errorPages** (array) - Optional - A list of custom error pages.

### Request Example
```json
{
  "action": {
    "proxy": {
      "upstream": "http://backend-service:8080"
    }
  },
  "errorPages": [
    {
      "codes": [404, 500],
      "redirect": {
        "code": 302,
        "url": "/error.html"
      }
    }
  ],
  "dos": "default"
}
```

### Response
#### Success Response (200)
- **action** (object) - The action configuration for the route.
- **dos** (string) - The DoS protection setting.
- **errorPages** (array) - A list of error page configurations.

#### Response Example
```json
{
  "action": {
    "proxy": {
      "upstream": "http://backend-service:8080"
    }
  },
  "errorPages": [
    {
      "codes": [404, 500],
      "redirect": {
        "code": 302,
        "url": "/error.html"
      }
    }
  ],
  "dos": "default"
}
```
```

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

### Deploy and Service for 'tea' Application in Kubernetes

Source: https://angie.software/anic/docs/custom-resources/cross-namespace-configuration

This YAML defines a Kubernetes Deployment and Service for the 'tea' application. The Deployment specifies the container image (`angiesoftware/angie-hello:plain-text`) and replicas, while the Service exposes the application on port 80 within the 'tea' namespace. Apply using `kubectl create -f tea.yaml`.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: tea
  namespace: tea
spec:
  replicas: 1
  selector:
    matchLabels:
      app: tea
  template:
    metadata:
      labels:
        app: tea
    spec:
      containers:
      - name: tea
        image: angiesoftware/angie-hello:plain-text
        ports:
        - containerPort: 8080
---
apiVersion: v1
kind: Service
metadata:
  name: tea-svc
  namespace: tea
spec:
  ports:
  - port: 80
    targetPort: 8080
    protocol: TCP
    name: http
  selector:
    app: tea

```

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

### Kubernetes Deployment Configuration for Angie Ingress Controller

Source: https://angie.software/anic/docs/installation/install

This snippet defines a Kubernetes Deployment for the Angie Ingress Controller. It specifies the container image, ports, readiness probe, resource requests, security context, and environment variables. The args define how ANIC will be configured, including the source for its configuration maps. Dependencies include a running Kubernetes cluster.

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: angie-ingress
  namespace: angie-ingress
spec:
  selector:
    matchLabels:
      app: angie-ingress
  template:
    metadata:
      labels:
        app: angie-ingress
        app.kubernetes.io/name: angie-ingress
    spec:
      serviceAccountName: angie-ingress
      automountServiceAccountToken: true
      containers:
      - image: docker.angie.software/angie-ingress:latest
        imagePullPolicy: IfNotPresent
        name: angie-ingress
        ports:
        - name: http
          containerPort: 80
        - name: https
          containerPort: 443
        - name: readiness-port
          containerPort: 8081
        - name: prometheus
          containerPort: 9113
        readinessProbe:
          httpGet:
            path: /angie-ready
            port: readiness-port
          periodSeconds: 1
        resources:
          requests:
            cpu: "100m"
            memory: "128Mi"
        securityContext:
          allowPrivilegeEscalation: false
          runAsUser: 101 #angie
          runAsNonRoot: true
          capabilities:
            drop:
            - ALL
        env:
        - name: POD_NAMESPACE
          valueFrom:
            fieldRef:
              fieldPath: metadata.namespace
        - name: POD_NAME
          valueFrom:
            fieldRef:
              fieldPath: metadata.name
        args:
          - -angie-configmaps=$(POD_NAMESPACE)/angie-config
        #- -default-server-tls-secret=$(POD_NAMESPACE)/default-server-secret
        #- -include-year
        #- -enable-cert-manager
        #- -enable-external-dns
        #- -v=3 # Enables extensive logging. Useful for troubleshooting.
        #- -report-ingress-status
        #- -external-service=angie-ingress
        #- -enable-prometheus-metrics
        #- -global-configuration=$(POD_NAMESPACE)/angie-configuration
```

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

### Describe GlobalConfiguration (Shell Command)

Source: https://angie.software/anic/docs/custom-resources/basic-tcp-udp

This command retrieves detailed information about a specific `GlobalConfiguration` resource, named 'angie-configuration' in the 'angie-ingress' namespace. It is used to verify the applied configuration and check for any events or status updates.

```bash
$ kubectl describe gc angie-configuration -n angie-ingress

```

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

### IngressMTLS Policy Configuration

Source: https://angie.software/anic/docs/installation/install

Defines the configuration for an IngressMTLS policy, specifying client certificate secret, verification settings, and depth.

```yaml
ingressMTLS:
  description: IngressMTLS defines an Ingress MTLS policy.
  type: object
  properties:
    clientCertSecret:
      type: string
    verifyClient:
      type: string
    verifyDepth:
      type: integer
```

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

### Apply Kubernetes Configuration

Source: https://angie.software/anic/docs/custom-resources/basic-configuration

Applies the Kubernetes configuration defined in the 'cafe.yaml' file using the kubectl command-line tool. This command is used to create the Deployments, Services, and Secrets defined in the YAML file.

```bash
$ kubectl create -f cafe.yaml

```
Tokens:
Raw