ap-application-load-balancer

AP-ALB Application Rules (The “Load Balancer listener” standard)

TL;DR:

The AP-ALB Ansible Role use YAML definitions as internal way to know what what is the desired final state of a ALB node. It means that, by default, there is not graphical user interface or API.
The control node (hint: can be your own notebook controling just one cheap VPS) will need root access to convert apply the YAML instructions.
- AP-ALB by design will try protect from human errors related to misconfigurations.
- AP-ALB alone, without human supervision is not able to protect from intentional configurations aimed to steal data from another applications.
For more advanced cases (to abstract the security issues with root or use non-YAML alternative), you can still use AP-ALB to control your nodes, but
- Use Ansible AWX / Ansible Tower
- Create your own custom GUI / custom API to pre-process the YAML files used by AP-ALB (or any other *-ALB implementation)
Read this documentation considering that some features AP-ALB are very exclusive to AP-ALB (or any solution that abstract HAProxy and OpenResty/NGinx) and do not have equivalent on cloud Load Balancers. Examples
- AP-ALB may both installed on dedicated Load Balancer servers and also on the servers that have the applications running
  - It means that you can replace your Apache and Nginx with AP-ALB.

AP-ALB Application Rules (The “Load Balancer listener” standard)

Overview of Applications Variables on servers using AP-ALB standard

Variables prefixed with app_ are used by Apps and Sysapps and have some extra customization via ALB Strategies.

These are key elements that form a single dictionary (think object) for the alb_apps (list of dictionaries) and alb_sysapps (list of dictionaries).

Quick example:

    alb_apps:

      - app_uid: "static-files"
        app_domain: "assets.example.org"
        app_root: "/var/www/html"
        app_alb_strategy: "files-local"

      - app_uid: "minio"
        app_domain: "minio.example.org"
        app_alb_proxy: "http://localhost:9091"
        app_alb_strategy: "proxy"

    alb_sysapps:

      - app_uid: "consul"
        app_domain: "consul..nip.io"
        app_alb_strategy: "proxy"
        app_alb_proxy: "http://127.0.0.1:8500"

New on v0.8.6-alpha: internally ALB will merge alb_sysapps_alb + alb_sysapps_always + alb_sysapps and alb_app_always + alb_apps. Ansible default behavior when the same variable is defined default and then some hosts also specify the variable is override. To make it easier for who want some apps/sysapps be on all nodes on a datacenter (and to avoid you use advanced features like hash_behaviour or implement plugins like leapfrogonline/ansible-merge-vars) we suggest use as convention alb_sysapps_always and alb_app_always.

Applications variables

app_*

Note: as v0.8.x, this section still maybe not reflex all implementation, but as here as a plan of action (fititnt, 2019-12-04 17:27 BRT)

app_uid

Required: always
Default: no default
Type of Value: String, [a-zA-Z0-9\-\_]
- Safe to use: Letters (lower and UPPERCASE), Numbers, Underline, Hyphen
- Not safe so safe to use (but not blocked): :, ;, UTF-8 characters (requires you system to support)
- Definely not use: blank spaces, /, \, control character (NUL \0, LF \n, …)
About uniqueness:
- Should be unique per node (but alb_apps and alb_sysapps can reuse same app_id)
- Is recommended to reuse ‘app_id` on different nodes that are same application
  - Example 1: Active-Active HA load balancing
  - Example 2: Active-Passive HA load balancing
- Note: Is not strongly required be unique per cluster of nodes, even if are very different applications or version of applications (think production vs staging)
Examples of Value: hello-world, hello_world

Internaly, AP-ALB use app_uid common name for configutation files (like /opt/alb/apps/.conf), default logs directory, default data diretory, internal aliases for which load balance and more.

app_state

Required: no (implicit value)
Default: “present”
Examples of Value: present, absent

app_state defaults to present, so you did not need to define. If you want remove one app, it’s configurations rules, log files, etc, you should at least once re-run one time with the same app_uid and app_state: absent for each node. After this, you can remove referentes to the old app/sysapp.

Note: implementators should not automaticaly remove backups based only on this configutation.

app_domain

Required: yes
Default: Default value is user configurable, based on app_uid
Type of Value: String, Regex String
- Check NGinx/Server Names for advanced options
Examples of Value: hello-world.example.org, hello-world.*, "hello-world..nip.io"

Most app_type expect at least one main domain so the the AP-ALB will know what to do when a request comes in.

app_domain_extras

Required: no
Default: no default
Type of Value: list of String, Regex String

Examples of Value:

# Empty list
app_domain_extras: []
# Please avoid using 'app_domain_extras: ' without defined itens and ': []' at the end

# List with 3 extra domains
app_domain_extras:
  - "hello-world.example.org"
  - "hello-world.*"
  - "hello-world..nip.io"

Advanced documentation
- Check NGinx/Server Names for advanced options

Use this to add extra domains to app_domain.

app_debug

Required: no
Default: alb_forcedebug^{(If defined)}, alb_default_app_forcedebug^{(If defined)}
Type of Value: Boolean
Examples of Value: yes, true, no, false

Mark one app in special to show more information, useful for debug. The information depends on the app_type implementation.

app_forcehttps

Required: no
Default: false, alb_default_app_forcehttps^{(If defined)}
Type of Value: Boolean
Examples of Value: yes, true, no, false

If true, acessing HTTP port will redirect 301 to the app_domain.

This option is one alternative to not use Ansible Host vars or Ansible Group Vars to define what Application run where. So you could have only one alb_apps alb_sysapps for the entire cluster (or more than one cluster if using more than one datacenter).

@TODO: implement this feature (fititnt, 2019-12-04 22:43 BRT)

app_index

Required: no
Default: no default, alb_default_app_index^{(If defined)}
Type of Value: String (name of files separed by spaces)
Examples of Value: index.html index.php
Advanced documentation
- https://docs.nginx.com/nginx/admin-guide/web-server/serving-static-content/

app_root

Required: no
Default: no default, alb_default_app_root^{(If defined)}
Type of Value: String (folder path)
Examples of Value: /var/html/www/
Advanced documentation
- https://docs.nginx.com/nginx/admin-guide/web-server/serving-static-content/#root

app_tags

Required: no
Default: no default
Type of Value: list of String
Examples of Value:

# Empty app_tags
app_domain_extras: []
# Please avoid using 'app_tags: ' without defined itens and ': []' at the end

# List with 3 extra domains
app_tags:
  - "my-tag-1"
  - "another-tag"
  - ""

app_data_*

app_data_* are one way to document specific applications that you care about make backups, or export/import from one node to another. The typical scenario is you document, at App/Sysapp level, what a different AP-ALB node should have to be fully operational.

As AP-ALB v0.8.2, this Role alone does not implement the full logistics of how to make the import/export/backup but you are encoraged to use these variables as one way to document or reuse future implementations.

Also keep in mind that even if AP-ALB implement these features, is likely that you would still need configure external services to store backups, since the priority here would be sincronize 2 nodes that, for example, do not have a shared (and often sloooow) filesystem.

app_data_directories

Required: no
Default: no default
Type of Value: list of Strings (list of absolute paths of directories on the node)

Examples of Value:

app_data_directories:
  - "/var/www/myapp"

app_data_files

Required: no
Default: no default
Type of Value: list of Strings (list of absolute paths of directories on the node)

Examples of Value:

app_data_files:
  - "/var/lib/rancher/k3s/server/node-token"
  - "/var/lib/rancher/k3s/server/db/state.db.bak"

app_data_hook_export_after

Required: no
Default: no default
Type of Value: String (Path to a Ansible Tasks file)
Examples of Value: "/delete-temporary-files.yml"

app_data_hook_export_before

Required: no
Default: no default
Type of Value: String (Path to a Ansible Tasks file)
Examples of Value: "/database-dump-to-file.yml"

app_data_hook_import_after

Required: no
Default: no default
Type of Value: String (Path to a Ansible Tasks file)
Examples of Value: "/populate-database-from-database-dump.yml"

app_data_hook_import_before

Required: no
Default: no default
Type of Value: String (Path to a Ansible Tasks file)
Examples of Value: "/install-requeriments-for-this-app-if-already-not-exist.yml"

app_healthcheck_*

app_healthcheck_extras ^(draft)

Required: no
Default: no default
Type of Value: list of Dictionaries contaning app_healthcheck_* additional to the default one
Examples of Value: /app-health-check

@TODO: this is a draft (fititnt, 2020-01-05 09:33 BRT)

app_healthcheck_path ^(draft)

Required: no
Default: no default
Type of Value: String
Examples of Value: /app-health-check

@TODO: this is a draft (fititnt, 2020-01-05 09:33 BRT)

app_healthcheck_value_ok ^(draft)

Required: no
Default: +OK
Type of Value: String
Examples of Value: Some string that health page have, Hello to my frontpage

@TODO: this is a draft (fititnt, 2020-01-05 09:33 BRT)

app_hook_*

`app_hook_after`

Required: no
Default: no default
Type of Value: String (path to a single Ansible Tasks file to execute)
Examples of Value: /hooks/app-static-html.yml, /ad-hoc-alb/hooks/debug.yml, /ad-hoc-alb/hooks/example/example_app_hook_after.yml

You can execute custom tasks specific to one app after deployed.

`app_hook_before`

Required: no
Default: no default
Type of Value: String (path to a single Ansible Tasks file to execute)
Examples of Value: /hooks/app-static-html.yml, /ad-hoc-alb/hooks/debug.yml, /ad-hoc-alb/hooks/example/example_app_hook_before.yml

You can execute custom tasks specific to one app before deployed.

`app_hook_onchange` ^(draft)

Equivalent of app_hook_after, but will only run if the alb app was changed.

`app_hook_[alb_play]_*`

Required: no
Default: no default
Type of Value: String (path to a single Ansible Tasks file to execute)
Examples of key names: app_hook_infra_after, app_hook_infra_before, app_hook_infra_onchange, app_hook_backup_before
Examples of Value: /hooks/app-static-html.yml, /ad-hoc-alb/hooks/debug.yml, /ad-hoc-alb/hooks/example/example_app_hook_after.yml

All options from app_hook_* are avalible to app_hook_[alb_play]_*. The main difference here is that [alb_play] act as one way to namespace your hooks.

The special variable alb_play could be hardcoded on your playbook or defined as command line variable (e.g. ansible-playbook -i hosts.yml my-playbook.yml -e="alb_play=infra") so only when this variable is defined, these hooks will be run.

@TODO: this explain some workarounds to archive this https://github.com/ansible/ansible/issues/17324

app_*_strategy

app_alb_strategy

Required: always (or will be ignored by OpenResty)
Default: no default
Type of Value: String or undefined or null
- Should be one ALB Strategies
- Can be a custom value defined by the user
Examples of Value: files-local, hello-world, proxy, raw, null

This option define what base OpenResty/NGinx template will be used as base for process all other variables.

app_backup_strategy

As version v0.8.1-alpha, this app_backup_strategy still not implemented.

app_ha_strategy

As version v0.8.1-alpha, this app_ha_strategy still not implemented.

app_healthcheck_strategy

As version v0.8.7-beta, this app_healthcheck_strategy still not implemented.

app_nlb_strategy

As version v0.8.1-alpha, this app_nlb_strategy still not implemented.

app_alb_*

app_alb_hosts

Required: no
Default: all hosts
Type of Value: list of String equivalent to ``

Examples of Value:

app_alb_hosts:
  - "ap_delta"
  - "ap_echo"

@TODO consider implement this planned (but not fully usable) feature as additional alternative to Ansible Inventory (fititnt, 2019-12-05 19:17 BRT)

app_alb_proxy

app_alb_strategy: proxy
Required: no
Default: no default
Type of Value: String
Examples of Value: http://127.0.0.1:8080,
Advanced documentation
- https://docs.nginx.com/nginx/admin-guide/web-server/reverse-proxy/

app_alb_proxy_defaults

app_type: proxy
Default: true

app_alb_proxy_defaults enable defaults inside the main proxy location block, like these ones:

location / {
    proxy_set_header Host $host;
    proxy_set_header X-Real-IP $remote_addr;
    # ...
}

Disable if you is having issues or what to make full customization with app_alb_proxy_raw. If you are OK with the defaults, use app_alb_proxy_params to just append new values

app_alb_proxy_location

app_alb_strategy: proxy
Required: no
Default: /
Type of Value: String
Examples of Value: /, = /, ~ \.php
Advanced documentation
- http://nginx.org/en/docs/http/ngx_http_core_module.html#location

app_alb_proxy_params

app_alb_strategy: proxy
Required: no
Default: no default, alb_default_app_alb_proxy_params^{(If defined)}

Examples of Value:

alb_apps:
  # Laravel example https://laravel.com/docs/deployment
  - app_uid: "laravel-site"
  - app_domain: ".example.com"
  - app_alb_strategy: "proxy"
  - app_alb_proxy_location: "~ \.php$"
  - app_alb_proxy: "unix:/var/run/php/php7.4-fpm.sock"
  - app_alb_proxy_params:
    - fastcgi_index: "index.php"
    - fastcgi_param: "SCRIPT_FILENAME $realpath_root$fastcgi_script_name"
    - include: "fastcgi_params"

app_alb_raw

Required: no
Default: no default
Type of Value: String (Path to a Jinja2 template file)

Examples of Value:

  alb_apps:
    - app_uid: "hello-world-minimal"
      app_domain: "hello-world-minimal..nip.io"
      app_alb_strategy: "minimal"
      app_alb_raw_file: "templates/example_app_alb_raw_file.conf.j2"
      app_alb_raw: >
        charset_types application/json;
        default_type application/json;

        location = /status {
            stub_status;
            allow all;
        }
        location = /ping {
            access_log off;
            return 200 "pong\n";
        }
        location = / {
            content_by_lua_block {
               local cjson = require "cjson"
               ngx.status = ngx.HTTP_OK
               ngx.say(cjson.encode({
                   msg = "Hello, hello-world-minimal! (from app_alb_raw)",
                   status = 200
               }))
            }
        }

See https://yaml-multiline.info if having issues with identation.

You can use app_alb_raw_file as alternative.

app_alb_raw_file

Required: no
Default: no default
Type of Value: String (Path to a Jinja2 template file)
Examples of Value: templates/example_app_alb_raw_file.conf.j2

Example of templates/example_app_alb_raw.conf.j2 content:

# File: github.com/fititnt/ansible-linux-ha-cluster/templates/example_app_alb_rawfile.conf.j2
# This file is just one example of using app_alb_raw_file instead of
# app_alb_raw template string

# With app_alb_raw you can't use item.app_uid variable, for example, but here
# you can

location / {
    content_by_lua_block {
       local cjson = require "cjson"
       ngx.status = ngx.HTTP_OK
       ngx.say(cjson.encode({
           msg = "Hello, ! (from app_alb_raw_file)",
           status = 200
       }))
    }
}

Deprecated app_* variables

app_raw_conf

Deprecated. Please use app_raw_alb and/or app_alb_raw_file

No default value for app_alb_strategy

Before AP-ALB v.0.8.x alb_apps[n]app_alb_strategy has default value of hello-word (and before that, files-local).

Now, value of app_alb_strategy is ommited, the alp_apps / alb_sysapps will be ignored by OpenResty.

The reason for this is allow on future have apps that can exist only for other reasons (for example, for NLB/HAProxy, or for Backup tasks). This also means that a same app group could have variables reused for different strategies

AP-ALB Application Rules compared to other load balancers

Azure Load balancer

https://docs.microsoft.com/pt-br/azure/load-balancer/

@TODO write small paragraph about AP-ALB and Azure Load Balancer (fititnt, 2019-12-15 06:44 BRT)

AWS Application Load Balancers Listeners

https://docs.aws.amazon.com/en_us/elasticloadbalancing/latest/application/load-balancer-listeners.html

@TODO write small paragraph about AP-ALB and AWS Application Load Balancers Listeners (fititnt, 2019-12-15 06:44 BRT)

Google Cloud Load Balancing

https://cloud.google.com/load-balancing/docs/apis

@TODO write small paragraph about AP-ALB and AWS Google Cloud Load Balancing (fititnt, 2019-12-15 06:44 BRT)

This site is open source. Improve this page.

ap-application-load-balancer

AP-ALB Application Rules (The “Load Balancer listener” standard)

Table of Contents

Overview of Applications Variables on servers using AP-ALB standard

Applications variables

app_*

app_uid

app_state

app_domain

app_domain_extras

app_debug

app_forcehttps

app_index

app_root

app_tags

app_data_*

app_data_directories

app_data_files

app_data_hook_export_after

app_data_hook_export_before

app_data_hook_import_after

app_data_hook_import_before

app_healthcheck_*

app_healthcheck_extras (draft)

app_healthcheck_path (draft)

app_healthcheck_value_ok (draft)

app_hook_*

app_hook_after

app_hook_before

app_hook_onchange (draft)

app_hook_[alb_play]_*

app_*_strategy

app_alb_strategy

app_backup_strategy

app_ha_strategy

app_healthcheck_strategy

app_nlb_strategy

app_alb_*

app_alb_hosts

app_alb_proxy

app_alb_proxy_defaults

app_alb_proxy_location

app_alb_proxy_params

app_alb_raw

app_alb_raw_file

Deprecated app_* variables

app_raw_conf

No default value for app_alb_strategy

AP-ALB Application Rules compared to other load balancers

Azure Load balancer

AWS Application Load Balancers Listeners

Google Cloud Load Balancing

app_healthcheck_extras ^(draft)

app_healthcheck_path ^(draft)

app_healthcheck_value_ok ^(draft)

`app_hook_after`

`app_hook_before`

`app_hook_onchange` ^(draft)

`app_hook_[alb_play]_*`