Docker Compose healthcheck சரியாக இயங்குவது எப்படி

Docker Compose healthcheck உண்மையில் செய்வது என்ன

Docker Compose healthcheck என்பது, Docker ஒரு குறிப்பிட்ட இடைவெளியில் container-க்குள் இயக்கும் ஒரு command ஆகும். Docker உங்கள் logs-ஐ படிக்காது, port-ஐ கண்காணிக்காது, process list-ஐ ஆய்வு செய்யாது. அது command-ஐ இயக்கி, exit code-ஐ படித்து, container-ல் ஒரே ஒரு நிலையைச் சேமிக்கும்: starting, healthy அல்லது unhealthy. Exit code 0 என்றால் healthy. வேறு எந்த exit code-மும் unhealthy என்பதைக் குறிக்கும். Exit code 2-ஐ Docker ஒதுக்கி வைத்துள்ளது. எனவே அதை திட்டமிட்டு ஒருபோதும் return செய்ய வேண்டாம்.

இதுவே முழு mechanism. பெரும்பாலான healthcheck சிக்கல்களின் காரணம் ஒன்றே: நீங்கள் எழுதிய command, நீங்கள் கேட்க நினைத்த கேள்விக்குப் பதிலாக வேறு கேள்விக்குப் பதிலளிக்கிறது. VPS-ல் compose file எழுதுவது எப்படி என்பது உங்களுக்கு ஏற்கனவே தெரியும் என்று இந்த வழிகாட்டி கருதுகிறது. Stack தவறான order-ல் start ஆகும் நிலை முதல் இது தொடர்கிறது.

services:
  api:
    image: ghcr.io/example/api:1.4.0
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:8080/healthz"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 30s

test value இரண்டு பயனுள்ள வடிவங்களைக் கொண்டுள்ளது. CMD-ல் தொடங்கும் list, shell இல்லாமல் command-ஐ நேரடியாக இயக்கும். எனவே pipes, && மற்றும் variable expansion வேலை செய்யாது. CMD-SHELL-ல் தொடங்கும் list, மீதமுள்ளவற்றை container-க்குள் உள்ள /bin/sh -c-க்கு ஒரே string ஆக அனுப்பும். Check-க்கு shell syntax தேவைப்படும் போது இதையே பயன்படுத்த வேண்டும். Plain string, CMD-SHELL ஆகக் கருதப்படும். சரியாக ["NONE"] கொண்ட list, image-ன் Dockerfile மூலம் சேர்க்கப்பட்ட healthcheck-ஐ நீக்கும்.

Check container-க்குள் இயக்கப்படுகிறது. எனவே அது குறிப்பிடும் ஒவ்வொரு binary-யும் அந்த image-ல் இருக்க வேண்டும். இதை முதலில் verify செய்யுங்கள். ஏனெனில் curl இல்லாத slim image, application log-ல் ஒருபோதும் தெரியாத காரணத்தால் container-ஐ நிரந்தரமாக unhealthy நிலையில் வைத்திருக்கும். இதை கைமுறையாகச் சோதிக்கவும்:

docker compose exec api curl --version

காணாமல் போன binary, OCI runtime exec failed: exec: "curl": executable file not found in $PATH: unknown எனப் பதிலளிக்கும். Alpine அடிப்படையிலான images-ல் பொதுவாக BusyBox wget இருக்கும். எனவே check, ["CMD", "wget", "-q", "-O", "-", "http://localhost:8080/healthz"] ஆக மாறும்.

interval, retries மற்றும் start_period எவ்வாறு இணைந்து செயல்படுகின்றன

நேரக் கணிப்பை 5 அமைப்புகள் கட்டுப்படுத்துகின்றன. இவற்றின் இயல்புநிலை மதிப்புகள் Compose-இலிருந்து அல்ல, Docker Engine-இலிருந்து பெறப்படுகின்றன.

• interval: container அதன் start period-ஐ கடந்த பிறகு, இரண்டு சரிபார்ப்புகளுக்கு இடையிலான நேரம். இயல்புநிலை 30s.
• timeout: ஒரு சரிபார்ப்பு இயங்குவதற்கு அனுமதிக்கப்படும் அதிகபட்ச நேரம். இந்த நேரத்துக்குள் முடியாவிட்டால் Docker அதை நிறுத்தி, அந்த இயக்கத்தை தோல்வியாகக் கணக்கிடும். இயல்புநிலை 30s.
• retries: நிலை unhealthy ஆக மாறுவதற்கு முன் தொடர்ச்சியாக ஏற்பட வேண்டிய தோல்விகளின் எண்ணிக்கை. இயல்புநிலை 3.
• start_period: container தொடங்கிய பிறகு வழங்கப்படும் சலுகைக் காலம். இயல்புநிலை 0s.
• start_interval: start period காலத்தில் சரிபார்ப்பு இயங்கும் இடைவெளி. இயல்புநிலை 5s. இதற்கு Docker Engine 25.0 அல்லது அதற்குப் பிந்தைய பதிப்பு தேவை.

முக்கியமான விதி இதுதான்: start period காலத்தில் தோல்வியடையும் சரிபார்ப்பு retries-இல் கணக்கிடப்படாது. container starting நிலையில் இருக்கும். சரிபார்ப்பு முதன்முறையாக வெற்றியடைந்தவுடன் container healthy ஆகி, பயன்படுத்தப்படாத நேரம் இருந்தாலும் start period உடனடியாக முடிவடையும். சரிபார்ப்பு தொடர்ந்து தோல்வியடையும் நிலையில் start period முடிந்தால், வழக்கமான எண்ணிக்கை தொடங்கும். container unhealthy எனக் குறிக்கப்படுவதற்கு முன், தொடர்ச்சியாக retries தோல்விகள் தேவைப்படும்.

ஆகவே, container தொடங்கிய நேரத்திலிருந்து unhealthy நிலையை அடையும் வரையிலான அதிகபட்ச நேரம் start_period + retries × interval + timeout ஆகும். மேலுள்ள கோப்பில் உள்ள மதிப்புகளின்படி, அது 30 + 5 × 13, அதாவது 95 seconds. deploy timeout அமைப்பதற்கு முன் இந்த எண்ணைக் குறித்துக் கொள்ளுங்கள். 60 seconds-க்குப் பிறகு நிறுத்தப்படும் rollout, இந்த container இறுதி நிலையை அடைவதை ஒருபோதும் காணாது.

இங்கு பொதுவாகச் செய்யப்படும் தவறு, மெதுவான தொடக்கத்தை சமாளிக்க retries மதிப்பை அதிகரிப்பதாகும். அது ஒருமுறை உதவினாலும், பின்னர் தொடர்ந்து பாதிப்பை ஏற்படுத்தும்: தொடங்குவதற்கு 8 retries தேவைப்பட்ட service, production-இல் எதுவும் கவனிக்கும் முன் தொடர்ச்சியாக 8 தோல்விகளை ஏற்றுக்கொள்ளும். அதற்குப் பதிலாக start_period ஐப் பயன்படுத்துங்கள். அது முதல் வெற்றிக்கு முன் மட்டுமே செயல்படும்.

தனியாக உள்ள depends_on எந்த உத்தரவாதத்தையும் வழங்காது

depends_on இன் சுருக்க வடிவமே பெரும்பாலான குழப்பங்களுக்கு காரணம்.

  api:
    depends_on:
      - db

இதன் பொருள் ஒன்றே: db container-ஐ, api container-க்கு முன் start செய்ய வேண்டும். Compose, container உருவாக்கப்பட்டு start செய்யப்படும் வரை காத்திருக்கும். PostgreSQL-ன் முதல் initialization முடியும் வரை அது காத்திருக்காது. Port 5432 connection-ஐ ஏற்கும் வரைவும் அது காத்திருக்காது. உங்கள் app சுமார் ஒரு விநாடிக்குப் பிறகு start ஆகிறது. அப்போது எந்த process-மும் listen செய்யாத port-க்கு அது connect செய்ய முயல்கிறது. பின்னர் அது exit ஆகிறது. Log-ல் Connection refused அல்லது server up ஆகியிருந்தாலும் recovery இன்னும் முடிவடையாதபோது FATAL: the database system is starting up என்பதைக் காணலாம்.

மக்கள் உண்மையில் விரும்புவது நீளமான வடிவமாகும்:

  api:
    depends_on:
      db:
        condition: service_healthy
        restart: true
      migrate:
        condition: service_completed_successfully

condition-க்கு மூன்று மதிப்புகள் உள்ளன. service_started என்பது சுருக்க வடிவில் உள்ள அதே மதிப்பு. service_healthy, dependency healthy என report செய்யும் வரை dependent service-ஐ தாமதப்படுத்துகிறது. இந்த நடைமுறை, அந்த dependency-யில் compose file-ல் அல்லது அதன் image-ல் healthcheck வரையறுக்கப்பட்டிருந்தால் மட்டுமே பொருள் கொண்டது. service_completed_successfully, database migration போன்ற one-shot container status 0-உடன் exit ஆகும் வரை காத்திருக்கிறது.

condition-க்கு அடுத்ததாக இரண்டு கூடுதல் fields உள்ளன. restart: true, dependency service-ஐ update செய்த பிறகு இந்த service-ஐ restart செய்ய Compose-க்கு அறிவுறுத்துகிறது. required: false, dependency இல்லாததை error-ஆகக் கருதாமல் warning-ஆகக் குறைக்கிறது.

இப்போது பலரைச் சிக்கவைக்கும் வரம்பைப் பார்ப்போம். Stack start ஆகும்போது இந்த conditions மதிப்பிடப்படுகின்றன. இவை start ordering மட்டுமே; supervision rule அல்ல. Database அதிகாலை 3 மணிக்கு restart ஆனால், service_healthy மீண்டும் மதிப்பிடப்படாது. அதை மீண்டும் பூர்த்தி செய்வதற்காக உங்கள் app-ம் restart செய்யப்படாது. உங்கள் application code தானாகவே மீண்டும் connect செய்ய வேண்டும். docker compose up --no-deps api இந்த முழு mechanism-ஐ திட்டமிட்டே தவிர்க்கிறது. docker start மூலம் container-ஐ நேரடியாக start செய்வதும் இதேபோல் செயல்படும்.

செயல்முறை இருக்கிறதா என்பதை அல்ல, தயார்நிலையைச் சோதிக்கும் check-ஐ எழுதுங்கள்

pgrep nginx போன்ற check, process table entry உள்ளது என்பதை நிரூபிக்கிறது. ஆனால் service ஒரு request-க்கு பதிலளிக்குமா என்பதை அது நிரூபிக்காது. ஒரு web application-ன் database pool செயலிழந்த பிறகும், அது நீண்ட நேரம் listening socket-ஐ திறந்த நிலையில் வைத்திருக்கலாம். அந்த முழு outage காலத்திலும் process check வெற்றியாகவே இருக்கும்.

Container செய்ய வேண்டிய பணியையே அதனிடம் செய்யச் சொல்லுங்கள்:

• HTTP service-க்கு, உண்மையான endpoint-ஐ request செய்யுங்கள். curl -fsS, -f காரணமாக 400 அல்லது அதற்கு மேற்பட்ட எந்த status-க்கும் non zero நிலையில் exit ஆகும். ஆகவே செயலிழந்த application-இலிருந்து வரும் 500, தோல்வியுற்ற check ஆகும்.
• PostgreSQL-க்கு pg_isready-ஐ பயன்படுத்துங்கள். Server connections-ஐ ஏற்றுக்கொண்டால் இது 0-ஆகவும், மறுத்தால் 1-ஆகவும், எந்தப் பதிலும் அளிக்காவிட்டால் 2-ஆகவும், நீங்கள் வழங்கிய parameters தவறாக இருந்தால் 3-ஆகவும் exit ஆகும்.
• Redis-க்கு redis-cli ping-ஐ பயன்படுத்துங்கள். இது PONG-ஐ print செய்து 0-ஆக exit ஆகும்.
• MariaDB-க்கு official image-ல் healthcheck.sh script உள்ளது. அதன் maintainers ஆவணப்படுத்தும் வடிவம் healthcheck.sh --connect --innodb_initialized ஆகும்.

pg_isready-க்கு தெரிந்துகொள்ள வேண்டிய ஒரு trap உள்ளது. காலியான data directory-யுடன் முதல் முறையாக start செய்யும்போது, official postgres image தனது initialisation-ஐ temporary server-க்கு எதிராக இயக்கும். அந்த server Unix socket-ல் மட்டுமே listening செய்யும். host argument இல்லாத pg_isready அந்த socket-ஐப் பயன்படுத்தும். எனவே TCP port 5432 உங்கள் application-க்கு இன்னும் மூடப்பட்டிருந்தாலும், அது "accepting connections" என்று பதிலளிக்கலாம். Check-ஐ TCP-க்கு வெளிப்படையாக point செய்தால் சிக்கல் தீரும். காரணம், temporary server அங்கு பதிலளிக்காது.

    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -p 5432 -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 10
      start_period: 30s

இரட்டை dollar signs பிழை அல்ல. File-ஐ வாசிக்கும் போது Compose தானாகவே $VAR-ஐ expand செய்யும். இதனால் உங்கள் host environment-இலிருந்து ஒரு value check-க்குள் நிரந்தரமாகச் சேர்க்கப்படும். $$ அதை ஒரு $ ஆக escape செய்கிறது. ஆகவே container-க்குள் இயங்கும் shell, container-ன் சொந்த environment-க்கு எதிராக அதை expand செய்யும்.

சரியான வரிசையில் தொடங்கும் postgres மற்றும் app stack

services:
  db:
    image: postgres:17.5
    environment:
      POSTGRES_USER: appuser
      POSTGRES_PASSWORD: ${DB_PASSWORD:?set DB_PASSWORD in .env}
      POSTGRES_DB: appdb
    volumes:
      - pgdata:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -h 127.0.0.1 -p 5432 -U $${POSTGRES_USER} -d $${POSTGRES_DB}"]
      interval: 5s
      timeout: 5s
      retries: 10
      start_period: 30s
    restart: unless-stopped

  api:
    image: ghcr.io/example/api:1.4.0
    environment:
      DATABASE_URL: postgres://appuser:${DB_PASSWORD}@db:5432/appdb
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-fsS", "http://localhost:8080/healthz"]
      interval: 10s
      timeout: 3s
      retries: 5
      start_period: 30s
    ports:
      - "127.0.0.1:8080:8080"
    restart: unless-stopped

volumes:
  pgdata:

அதைத் தொடங்கி, நிலைகள் மாறுவதைப் பார்க்கவும்:

docker compose up -d
docker compose ps

STATUS நெடுவரிசை, அடைப்புக்குறிகளுக்குள் health நிலையை காட்டுகிறது. ஆரோக்கியமான இணை இரு வரிகளிலும் Up 41 seconds (healthy) எனக் காட்டும். Database இன்னும் initialising நிலையில் இருக்கும்போது, db என்பது Up 4 seconds (health: starting) எனக் காட்டும். மேலும் api பட்டியலில் இருக்காது, ஏனெனில் Compose அதை இன்னும் உருவாக்கவில்லை.

ஒரு check வெற்றியடைந்ததா அல்லது தோல்வியடைந்ததா என்பதை அறிய, health log-ஐப் படிக்கவும்:

docker inspect --format '{{json .State.Health}}' "$(docker compose ps -q db)"

Docker கடைசி சில முடிவுகளைச் சேமிக்கிறது. ஒவ்வொரு முடிவிலும் start time, end time, ஒரு ExitCode மற்றும் command-ன் Output இருக்கும். சேமிக்கப்பட்ட output சுருக்கப்படும். ஆகவே, பெரிய page body-ஐ வெளியிடும் check பயனற்ற log entry-ஐ உருவாக்கும். Checks-ஐ அமைதியாக வைத்திருக்கவும்.

ஒரு container unhealthy ஆகும்போது Docker செய்யும் செயல்

எதுவும் இல்லை. இதுவே பெரும்பாலானவர்களை ஆச்சரியப்படுத்தும் பதில்.

ஒரே host-ல் இயங்கும் Docker Engine, unhealthy container-ஐ restart செய்யாது. restart: unless-stopped policy, main process வெளியேறும்போது செயல்படும். ஆனால் unhealthy container வெளியேறியிருக்காது. Compose அதை கவனிக்காமல் விட்டுவிடும் நிலையில், அது ஒரு வாரம் unhealthy நிலையில் இருக்கலாம். Swarm mode, unhealthy tasks-ஐ மாற்றும். ஆனால் ஒரு server-ல் இயங்கும் வழக்கமான Compose stack அவ்வாறு செய்யாது.

இதற்கு இரண்டு நேர்மையான வழிகள் உள்ளன. Process பழுதடைந்ததை அறிந்தவுடன் அது exit ஆகுமாறு அமைக்கவும். இதனால் restart policy செயல்படக்கூடிய நிலை உருவாகும். அல்லது வெளிப்புறத்திலிருந்து state-ஐ கண்காணித்து alert அனுப்பவும். உங்கள் healthcheck அழைக்கும் அதே endpoint-க்கு Uptime Kuma monitor-ஐ அமைத்தால், பழுதடைந்த dependency இரண்டு இடங்களிலும் தெரியும். பயனரிடமிருந்து அறியும் முன்பே monitor மூலம் தகவல் கிடைக்கும். Traffic, Traefik reverse proxy வழியாக app-ஐ அடைந்தால், backend பற்றிய proxy-யின் சொந்த பார்வை Docker health state-இலிருந்து தனித்தது என்பதை நினைவில் கொள்ளவும். எனவே, ஒன்று மற்றொன்றை மாற்றாது.

ஒருபோதும் healthy நிலைக்கு மாறாத check-ஐ பிழைத்திருத்துதல்

அதே container-இல் சரியான command-ஐ நீங்களே இயக்கி, exit code-ஐப் பாருங்கள்:

docker compose exec api curl -fsS http://localhost:8080/healthz; echo "exit=$?"

Container இன்னும் unhealthy என்று தெரிவிக்கும் நிலையில் இங்கு exit=0 இருந்தால், உங்கள் compose test நீங்கள் இப்போது தட்டச்சு செய்ததிலிருந்து வேறுபடுகிறது. Shell syntax தேவைப்பட்ட இடத்தில் பொதுவாக CMD பயன்படுத்தப்பட்டிருக்கும்.

மீதமுள்ள பெரும்பாலான சிக்கல்களுக்கு இரண்டு தவறுகளே காரணம். முதல் தவறு தவறான port. Healthcheck container-க்குள் இயங்குகிறது. எனவே அது container port-ஐப் பயன்படுத்த வேண்டும்; வெளியிடப்பட்ட host port-ஐ ஒருபோதும் பயன்படுத்தக் கூடாது. ports: - "8080:3000" உடன் application 3000-ல் listening செய்கிறது. ஆனால் http://localhost:8080-ஐச் சரிபார்க்கும் check எப்போதும் தோல்வியடையும்; browser-இல் site சரியாக இயங்கினாலும் இதே நிலை இருக்கும். இரண்டாவது தவறு தவறான host. Check-க்குள் localhost என்பது அதே container-ஐக் குறிக்கும். தன்னையே சரிபார்க்க இது சரியானது. ஆனால் அருகிலுள்ள மற்றொரு container-ஐச் சரிபார்க்க இது தவறானது. அதற்கு service name தேவைப்படும். எடுத்துக்காட்டாக, db.

இறுதியாக, users errors-ஐக் காணும்போது healthcheck வெற்றி பெறும் நிலையும் உள்ளது. Endpoint எந்த உண்மையான செயல்பாட்டையும் செய்யாமல் static 200-ஐத் திருப்பும்போது இது நிகழ்கிறது. Database கிடைக்கவில்லை என்பதை database-ஐ query செய்யாத readiness endpoint கண்டறிய முடியாது. குறைந்த செலவுடைய ஒரு உண்மையான query-ஐ அது இயக்குமாறு அமைக்கவும்.

FAQ

depends_on-ல் database healthy என்று குறிப்பிடப்பட்டிருந்தும், எனது app ஏன் இன்னும் connect ஆகத் தவறுகிறது?

ஏனெனில் condition: service_healthy stack தொடங்கும்போது ஒருமுறை மட்டுமே மதிப்பிடப்படுகிறது. அதன் பிறகு அது எதையும் கண்காணிக்காது. பின்னர் database container மீண்டும் தொடங்கினால், அந்த நிபந்தனையை மீண்டும் பூர்த்தி செய்வதற்காக Compose உங்கள் application-ஐ மீண்டும் தொடங்காது. எனவே, உங்கள் application code-க்கு தனியான reconnect மற்றும் retry logic தேவை. docker start அல்லது docker compose up --no-deps மூலம் ஒரே container-ஐ தொடங்கும்போதும் இந்த நிபந்தனை எந்தச் செயல்பாடும் செய்யாது.

image ஏற்கனவே healthcheck-ஐ வரையறுத்திருந்தால், எனக்கு healthcheck தேவைப்படுமா?

பொதுவாகத் தேவையில்லை. அதை override செய்வது பெரும்பாலும் பின்னடைவை ஏற்படுத்தும், ஏனெனில் அந்த software-க்கு readiness என்பதன் பொருள் என்ன என்பதை image maintainer நன்கு அறிந்திருப்பார். image-ன் check உங்கள் setup-க்கு தவறாக இருந்தால் மட்டுமே சொந்த check-ஐச் சேர்க்கவும். எடுத்துக்காட்டாக, நீங்கள் மாற்றிய port-ஐ அது probe செய்தால் இதைச் செய்யலாம். image healthcheck-ஐ முடக்க, service-ல் test: ["NONE"] அல்லது disable: true அமைக்கவும்.

healthcheck-க்கு curl அல்லது wget பயன்படுத்த வேண்டுமா?

image-ல் ஏற்கனவே உள்ள command-ஐப் பயன்படுத்தவும். அதை நம்புவதற்கு முன் docker compose exec <service> curl --version மூலம் அது உள்ளதா என்பதை உறுதிப்படுத்தவும். Debian அடிப்படையிலான பல images-ல் இவற்றில் எதுவும் இருக்காது. Alpine அடிப்படையிலான images-ல் BusyBox wget இருக்கும். healthcheck இயக்குவதற்காக மட்டும் ஒரு package-ஐ image-ல் சேர்க்க வேண்டாம். குறிப்பாக software-உடன் pg_isready அல்லது redis-cli போன்ற சொந்த client இருந்தால் இது தேவையில்லை.

unhealthy container தானாகவே restart செய்யப்படுமா?

ஒரே host-ல் Docker Engine இதைச் செய்யாது. Restart policies, process வெளியேறுவதற்கு மட்டுமே பதிலளிக்கும்; health state-க்கு அல்ல. எனவே, வேறு ஏதாவது செயல்படும் வரை unhealthy container இயங்கிக்கொண்டே இருந்து, செயலிழந்த நிலையிலேயே இருக்கும். தோல்வியைக் கண்டறியும் போது process வெளியேறும் வகையில் அமைக்கவும். அல்லது state குறித்து alert அனுப்பும் external monitor-ஐ இயக்கவும்.

start_period எவ்வளவு நீளமாக இருக்க வேண்டும்?

நீங்கள் அளந்த slowest legitimate first start-க்கு போதுமான நேரத்தையும், அதற்கு மேலான ஒரு margin-ஐயும் வழங்கும் அளவு இருக்க வேண்டும். காலியான volume-ஐப் பயன்படுத்தி docker compose up மூலம் இதை அளவிடவும். ஏனெனில் database-ன் முதல் start, அதற்குப் பிறகான ஒவ்வொரு start-ஐவிடவும் மிகவும் மெதுவாக இருக்கும். மிக நீளமான start period, முதல் unhealthy verdict-ஐ மட்டும் தாமதப்படுத்தும். மிக அதிகமான retries, container-ன் முழு ஆயுட்காலத்திலும் check-ன் கடுமையை குறைக்கும். இதுவே மோசமான தோல்வியாகும்.