ASAB Maestro descriptor¶

Deskriptory jsou YAML soubory žijící v knihovně. Každá aplikace se skládá ze skupiny deskriptorů /Site/<application name>/Descriptors/.

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

Note

Deskriptory jsou poskytovány autory každé aplikace.

Struktura deskriptoru¶

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

define:
  type: rc/descriptor
  name: MongoDB dokumentová databáze
  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", "HOTOVO"]
    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í Jinja2 šablony, které se rozšiřují při aplikaci deskriptoru.

Běžné parametry:

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

Note

Ostatní parametry mohou být specifikovány v rámci deskriptorů, v modelu nebo poskytovány technologiemi.

Technologie¶

Nejen, že jsou složeny vícenásobné knihovní soubory do konečné konfigurace. Existují také technologie hrající své role. Technologie jsou součástí mikroservisu ASAB Remote Control a poskytují další konfiguraci clusteru.

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

Zjistěte více o Technologiích

Složitelnost¶

Deskriptory mohou být přepsány v nasazení prostřednictvím specifických konfiguračních možností nebo prostřednictvím modelu.

/Site/<application name>/Descriptors/__commons__.yaml soubor knihovny je společný základ pro všechny deskriptory aplikace. Specificky obsahuje položky pro režim sítě, politiku restartu, logování a další.
Specifický descriptor služby (např. /Site/<application name>/Descriptors/nginx.yaml) je vrstvený nad obsahem __commons__.yaml
Model může přepsat descriptor.

Merge algoritmus

Tato složitelnost je realizována prostřednictvím slučovacího algoritmu. Stejný algoritmus najdete použitý v několika případech, kde kusy z různých zdrojů vedou do funkční konfigurace stránek.

Vrstvení knihovny

Chcete-li získat úplný obraz o knihovně v rámci ASAB Maestro, zjistěte více o vrstvách knihovny ASAB.

Sekce¶

Sekce `define`¶

define:
  type: rc/descriptor
  name: <srozumitelný název>
  url: <URL s relevantními informacemi>

type musí být rc/descriptor.

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

Sekce `params`¶

Specifikujte parametry pro šablonování tohoto a všech ostatních deskriptorů. Jakýkoli parametr specifikovaný v této sekci může být použit ve 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, také secrets mohou být použity jako parametry pro šablonování. Jejich hodnota však není specifikována v deskriptoru, ale generována a uložena v Vaultu. Secret můžete přizpůsobit specifikování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}}"

Warning

Části deskriptoru jsou použity přímo k přípravě docker-compose.yaml. Sekce secrets může být specifikována také v docker-compose.yaml. Nicméně, tato funkcionalita Docker Compose je v rámci ASAB Maestro vynechána a plně nahrazena sekcí secrets deskriptoru.

Sekce `descriptor`¶

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

Jsou prováděny následující transformace:

Šablony Jinja2 proměnných jsou rozšířeny.
Verze z ../Versions/... je přidána k image, pokud není přítomna.
Specifické technologie provádějí vlastní transformace, které jsou obvykle označeny null.

Detaily o `volumes`¶

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

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

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

Sekce `files`¶

Tato sekce specifikuje, které soubory mají být kopírovány do podsložky instance adresáře stránek (tj. /opt/site/...). Následně může být tento obsah zpřístupněn kontejneru instance příslušnou položkou volumes.

Seznam souborů pomocí následujícího schématu:

files:
  - destination:
      source: file_name.txt

NEBO

files:
  - destination:
      content: |
        Víceřádkový text
        který bude zapsán do
        cílové cesty.

Cíl¶

Existují tři možné destinace:

Tato služba
Jiná služba
ZooKeeper

1. Tato služba¶

Cesta souboru je relativní k cíli v adresáři stránek.

Například, 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 INSTANCE ID instance mongo mongo-1.

2. Jiná služba¶

Použijte URL se schématem service, abyste zacílili soubor do jiné služby.

Například, tento záznam v JAKÉMKOLI deskriptoru 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 ve modelu také přítomna a její INSTANCE ID je mongo-1.

3. ZooKeeper¶

Použijte schéma URL zk, abyste specifikovali cestu v ZooKeeper, kde chcete soubor nahrát. Soubor je v režimu "řízeného". 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 uzel ZooKeeper s cestou /asab/library/settings/lmio-library-settings.json vytvořen nebo aktualizován, pokud již existuje.

Zdroj¶

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

Zdroj může být jak soubor, tak složka. Cesta složky musí končit lomítkem.

Zkrácené syntaxe zdroje souboru

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

Tento záznam zkopíruje soubor /Site/ASAB Maestro/Files/mongo/script/mongo-init.js do /opt/site/mongo-1/script/mongo-init.js, pokud je identifikace instance mongo-1:

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

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

files:
  - "conf/"

Soubory nejsou šablonovány

Na rozdíl od deskriptorů a modelů, soubory uložené v adresáři /Site/<application name>/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 použít šablonování v souboru, vložte soubor přímo do deskriptoru, pomocí operátoru víceřádkového řetězce ("|").

Obsah¶

Definujte obsah souboru přímo v deskriptoru. To je zvláště vhodné pro krátké soubory a/nebo soubory, které vyžadují parametry poskytované maestro.

Literalský styl pomocí trubky (|) v yaml souboru umožňuje psaní víceřádkových řetězců (blokových scalarů).

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

Klíčové slovo content může být vynecháno pro stručnost.

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

Sekce `sherpas`¶

Sherpas jsou pomocné kontejnery, které jsou spouštěny spolu s hlavními kontejnery instance. Kontejnery sherpa by měly poměrně rychle dokončit a nejsou restartovány. Sherpa kontejnery, které úspěšně skončí (s kódem ukončení 0) jsou okamžitě smazány.

Příklad:

sherpas:
  init:
    image: library/mongo
    entrypoint: ["mongosh", "--nodb", "--file", "/script/mongo-init.js"]
    command: ["echo", "HOTOVO"]
    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 sherpa je šablona pro příslušnou část souboru 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 sherpa, protože tento obraz je vždy přítomen a nemusí být stažován.