Deskriptor ASAB Maestro¶

Deskriptory jsou soubory YAML uložené v Knihovně. Každá aplikace se skládá ze skupiny deskriptorů /Site/<název aplikace>/Descriptors/.

Deskriptor poskytuje podrobné informace o službě a/nebo technologii. Deskriptore slouží jako specifická rozšíření modelu.

Poznámka

Popisy poskytují autoři každé žádosti.

Struktura deskriptoru¶

Příklad /Site/ASAB Maestro/Descriptors/mongo.yaml:

define:
  type: rc/descriptor
  name: MongoDB document database
  url: https://github.com/mongodb/mongo

descriptor:
  image: library/mongo

  volumes:
    - "{{SLOW_STORAGE}}/{{INSTANCE_ID}}/data:/data/db"
    - "{{SITE}}/{{INSTANCE_ID}}/conf:/etc/mongo:ro"

  command: mongod --config /etc/mongo/mongod.conf --directoryperdb

  healthcheck:
    test: ["CMD-SHELL", 'echo "db.runCommand(\"ping\").ok" | mongosh 127.0.0.1:27017/rs0 --quiet']
    interval: 60s
    timeout: 10s
    retries: 5
    start_period: 30s

sherpas:
  init:
    image: library/mongo
    entrypoint: ["mongosh", "--nodb", "--file", "/script/mongo-init.js"]
    command: ["echo", "DONE"]
    volumes:
    - "{{SITE}}/{{INSTANCE_ID}}/script:/script:ro"
    - "{{SITE}}/{{INSTANCE_ID}}/conf:/etc/mongo:ro"
    depends_on: ["{{INSTANCE_ID}}"]
    environment:
      MONGO_HOSTNAMES: "{{MONGO_HOSTNAMES}}"

files:
  - "conf/mongod.conf": |
      net:
        bindIp: 0.0.0.0
        port: 27017
      replication:
        replSetName: rs0
  - "script/mongo-init.js"

Šablonování¶

Deskriptory využívají šablony Jinja2, které se rozvinou, když je deskriptor aplikován.

Běžné parametry:

{{NODE_ID}}: Identifikace uzlu / hostname hostitelského stroje (node1).
{{SERVICE_ID}}: Identifikace služby (např. mongo).
{{INSTANCE_ID}}: Identifikace instance (např. mongo-2).
{{INSTANCE_NO}}: Číslo instance (např. 2).
{{SITE}}: Adresář s konfigurací webu na hostitelském stroji (např. /opt/site).
{{FAST_STORAGE}}: Adresář s rychlým úložištěm na hostitelském stroji (např. /data/ssd).
{{SLOW_STORAGE}}: Adresář s pomalým úložištěm na hostitelském stroji (např. /data/hdd).

Poznámka

Ostatní parametry lze specifikovat v deskriptorech, v modelu nebo je zajistit prostřednictvím technologií.

Vlastní filtry Jinja2 registrované ASAB Remote Control mohou transformovat hodnoty šablon — například {{MY_SECRET|argon2_hash}} vytváří deterministický Argon2id hash tajemství.

Technologie¶

Některé z nich také zavádějí specifické sekce do Deskriptorů.

Zjistěte více o Technologiích

Složitost¶

Soubor /Site/<název aplikace>/Descriptors/__commons.yaml__ Knihovny je společnou základnou pro všechny deskriptory aplikace. Obsahuje konkrétně položky pro režim sítě, restartovací politiku, protokolování a další.
Specifický deskriptor služby (např. /Site/<název aplikace>/Descriptors/nginx.yaml) je vrstvený nad obsahem __commons__.yaml
Model může přepsat deskriptor.

Sloučit algoritmus

Tato skladebnost je implementována prostřednictvím slučovacího algoritmu. Ten samý algoritmus naleznete použitý v několika případech, kdy kousky z různých zdrojů vedou k funkční konfiguraci webu.

Vrstevnění knihovny

Chcete-li získat úplný přehled o Knihovně v rámci ASAB Maestro, seznamte se také s vrstvením knihovny ASAB.

Sekce¶

Sekce `define`¶

define:
  type: rc/descriptor
  name: <human-readable name>
  url: <URL with relevant info>

type musí být rc/descriptor.

Položky name a url poskytují informace o službě a/nebo technologii.

Sekce `params`¶

Určete parametry pro šablonování tohoto a všech ostatních Deskriptorů. Jakýkoli parametr specifikovaný v této sekci lze použít v dvojitých složených závorkách pro šablonování Jinja2.

define:
  type: rc/descriptor

params:
  MY_PARAMETER: "ABCDEFGH"

descriptor:
  environment: "{{MY_PARAMETER}}"

Sekce `secrets`¶

Podobně jako params mohou být tajemství použita také jako parametry pro tvorbu šablon. Jejich hodnota však není určena v popisu, ale je generována a uložena ve Vault. Tajemství si můžete přizpůsobit určením type a length. Výchozí je "token" o délce 64 bytů.

define:
  type: rc/descriptor

secrets:
  MY_SECRET:
    type: token
    length: 32

descriptor:
  environment: "{{MY_SECRET}}"

Varování

Části popisu jsou používány přímo k přípravě docker-compose.yaml. Sekce secrets může být také specifikována v docker-compose.yaml. Tato funkcionalita Docker Compose je však v ASAB Maestro vynechána a je plně nahrazena sekcí secrets v popisu.

Sekce `descriptor`¶

Sekce descriptor je šablona pro sekci service souboru docker-compose.yaml.

Následující transformace byly provedeny:

Proměnné Jinja2 jsou rozvinuty.
Verze z ../Versions/... je připojena k image, pokud tam není přítomna.
Specifické technologie provádějí vlastní transformace, obvykle jsou označeny null.

Podrobnosti o `volumes`¶

Služba má k dispozici následující tři úložiště pro jejich trvalá data:

{{SITE}}: adresář webu (např. /opt/site/...)
{{SLOW_STORAGE}}: pomalé úložiště (např. /data/hdd/...)
{{FAST_STORAGE}}: rychlé úložiště (např. /data/ssd/...)

Každá instance může vytvořit podsložku v kterékoliv z výše uvedených umístění pojmenovanou podle svého instance_id.

Sekce `files`¶

Tato sekce určuje, které soubory mají být zkopírovány do podadresáře instance v adresáři webu (tj. /opt/site/...). Následně může být tento obsah zpřístupněn kontejneru instance prostřednictvím příslušného záznamu volumes.

Vypište soubory podle následujícího schématu:

files:
  - destination:
      source: file_name.txt

OR

files:
  - destination:
      content: |
        Multiline plain text
        that will be written into
        the destination path.

Cíl¶

Existují tři možné destinace:

Tato služba
Jiná služba
ZooKeeper

1. Tato služba¶

Zadaná cesta k souboru je relativní k cíli v adresáři webu.

Ve příkladu, tento záznam v deskriptoru...

files:
- script/mongo-init.js:
    source: some_source_dir/mongo-init.js

...vytvoří soubor /opt/site/mongo-1/script/mongo-init.js, pokud je ID INSTANCE mongo instance mongo-1.

2. Jiná služba¶

Použijte URL s protokolem service k cílení souboru do jiné služby.

Například tento záznam v JAKÉMKOLIV popisu služby v modelu...

files:
- service://mongo/script/mongo-init.js:
    source: some_source_dir/mongo-init.js

...vytvoří soubor /opt/site/mongo-1/script/mongo-init.js, pokud je instance mongo přítomna v modelu a její ID INSTANCE je mongo-1.

3. Ošetřovatel v zoo¶

Použijte schéma URL zk k určení cesty v ZooKeeper, kam nahrát soubor. Soubor je v režimu „spravováno“. To znamená, že je vždy aktualizován podle aktuálního stavu knihovny.

files:
  - zk:///asab/library/settings/lmio-library-settings.json:
      source: asab-library/setup.json

V tomto příkladu bude vytvořen uzel ZooKeeper s cestou /asab/library/settings/lmio-library-settings.json, nebo aktualizován, pokud již existuje.

Zdroj¶

Zdroj je relativní cesta ke složce knihovny přiřazená jako /Site/<application>/Files/<service>/. Např. pro službu mongo odkazuje na /Site/ASAB Maestro/Files/mongo/.

Zdroj může být buď soubor, nebo složka. Cesta ke složce musí končit lomítkem.

!!! tip „Zkratky syntaxe zdrojového souboru“

Pokud v deklaraci chybí zdroj, sdílí stejnou cestu jako cíl.

Tento záznam kopíruje soubor /Site/ASAB Maestro/Files/mongo/script/mongo-init.js do /opt/site/mongo-1/script/mongo-init.js, za předpokladu, že identifikace instance je mongo-1:

```yaml
files:
  - "script/mongo-init.js"
```

Podobný záznam s koncovým znakem / zkopíruje celý adresář z /Site/ASAB Maestro/Files/mongo/script/conf do adresáře /opt/site/mongo-1/conf/.

```yaml
files:
  - "conf/"
```

Soubory nejsou šablonovány

Na rozdíl od Deskriptorů a modelu, soubory uložené v adresáři /Site/<název aplikace>/Files/<service_id>/ nejsou šablonovány. To znamená, že složené závorky s parametry nejsou nahrazeny příslušnými hodnotami. Pokud potřebujete ve souboru používat šablony, vložte soubor přímo do Deskriptore prostřednictvím operátoru pro vícenásobný řetězec ("|").

Obsah¶

Uveďte obsah souboru přímo v deskriptoru. To je zvláště výhodné pro krátké soubory a/nebo soubory, které vyžadují parametry poskytnuté Maestrem.

Doslovný styl použitím svislíku (|) v souboru yaml umožňuje psaní víceliniových řetězců (blokových skalárů).

files:
  - "conf/mongod.conf":
      content: |
        net:
          bindIp: 0.0.0.0
          port: 27017
        replication:
          replSetName: rs0

Klíčové slovo content lze vynechat pro stručnost.

files:
  - "conf/mongod.conf": |
      net:
        bindIp: 0.0.0.0
        port: 27017
      replication:
        replSetName: rs0

Sekce `sherpas`¶

Šerpové jsou pomocné kontejnery, které jsou spouštěny společně s hlavními kontejnery instance. Kontejnery šerpy se očekává, že skončí relativně rychle a nejsou restartovány. Šerpové, kteří úspěšně skončí (s výstupním kódem 0), jsou okamžitě odstraněni.

Příklad:

sherpas:
  init:
    image: library/mongo
    entrypoint: ["mongosh", "--nodb", "--file", "/script/mongo-init.js"]
    command: ["echo", "DONE"]
    volumes:
    - "{{SITE}}/{{INSTANCE_ID}}/script:/script:ro"
    - "{{SITE}}/{{INSTANCE_ID}}/conf:/etc/mongo:ro"
    depends_on: ["{{INSTANCE_ID}}"]
    environment:
      MONGO_HOSTNAMES: "{{MONGO_HOSTNAMES}}"

Toto definuje init sherpa kontejner. Název kontejneru sherpa by byl mongo-1-init, parametr INSTANCE_ID zůstává mongo-1.

Obsah sherpy je šablona pro relevantní část docker-compose.yaml.

Pokud sherpa nespecifikuje image, použije se obraz služby včetně verze. Alternativně doporučujeme použít docker.teskalabs.com/asab/asab-governator:stable jako obraz pro sherpu, protože tento obraz je vždy k dispozici a není třeba jej stahovat.

Deskriptor ASAB Maestro¶

Struktura deskriptoru¶

Šablonování¶

Technologie¶

Složitost¶

Sekce¶

Sekce define¶

Sekce params¶

Sekce secrets¶

Sekce descriptor¶

Podrobnosti o volumes¶

Sekce files¶

Cíl¶

1. Tato služba¶

2. Jiná služba¶

3. Ošetřovatel v zoo¶

Zdroj¶

Obsah¶

Sekce sherpas¶

Sekce `define`¶

Sekce `params`¶

Sekce `secrets`¶

Sekce `descriptor`¶

Podrobnosti o `volumes`¶

Sekce `files`¶

Sekce `sherpas`¶