Debian Codegraph @

ansible_collections/containers/podman/docs/connection_plugins.md

raw
1 # Podman and Buildah Connection Plugins
2
3 This document provides comprehensive information about the Podman and Buildah connection plugins included in the `containers.podman` Ansible collection.
4
5 ## Table of Contents
6
7 1. [Overview](#overview)
8 2. [Installation and Setup](#installation-and-setup)
9 3. [Podman Connection Plugin](#podman-connection-plugin)
10 4. [Buildah Connection Plugin](#buildah-connection-plugin)
11 5. [Configuration Options](#configuration-options)
12 6. [Simple Usage Examples](#simple-usage-examples)
13 7. [Advanced Usage Examples](#advanced-usage-examples)
14 8. [Performance and Best Practices](#performance-and-best-practices)
15 9. [Troubleshooting](#troubleshooting)
16 10. [Migration from Legacy Plugins](#migration-from-legacy-plugins)
17
18 ## Overview
19
20 The connection plugins enable Ansible to execute tasks directly inside Podman containers and Buildah working containers. These plugins provide a seamless way to manage containerized environments using standard Ansible playbooks and tasks.
21
22 ### Key Features
23
24 - **Direct container execution**: Run Ansible tasks inside containers without SSH
25 - **Fail-fast error handling**: No implicit retries; commands return rc/stdout/stderr to Ansible
26 - **Performance optimization**: Connection caching and mount detection for efficient file operations
27 - **Environment management**: Inject environment variables and configure container runtime
28 - **Unicode and special character support**: Handle complex file paths and command arguments
29 - **Privilege escalation**: Support for sudo and other privilege escalation methods
30 - **Timeout configuration**: Optional command timeout (default 0 = no timeout)
31
32 ### Use Cases
33
34 - **Application deployment**: Deploy applications directly into containers
35 - **Container configuration**: Configure running containers with Ansible tasks
36 - **Multi-container orchestration**: Manage complex containerized applications
37 - **Development environments**: Set up and configure development containers
38 - **Testing and CI/CD**: Run tests and build processes inside containers
39 - **Container image customization**: Modify and configure container images using Buildah
40
41 ## Installation and Setup
42
43 ### Prerequisites
44
45 - Ansible 2.9 or later
46 - Podman 3.0+ (for Podman connection plugin)
47 - Buildah 1.20+ (for Buildah connection plugin)
48 - Python 3.6+ on the Ansible control node
49
50 ### Installation
51
52 ```bash
53 # Install from Ansible Galaxy
54 ansible-galaxy collection install containers.podman
55
56 # Or install from source
57 git clone https://github.com/containers/ansible-podman-collections.git
58 cd ansible-podman-collections
59 ansible-galaxy collection build
60 ansible-galaxy collection install containers-podman-*.tar.gz
61 ```
62
63 ## Podman Connection Plugin
64
65 The Podman connection plugin (`containers.podman.podman`) allows Ansible to execute tasks inside running Podman containers.
66
67 ### Podman Connection Plugin Features
68
69 - **Container lifecycle management**: Automatically detect and connect to running containers
70 - **Mount point detection**: Optimize file transfers by detecting shared mounts
71 - **Environment variable injection**: Pass environment variables from inventory to container
72 - **Connection caching**: Cache container information for improved performance
73 - **Multiple execution modes**: Support for different container runtime configurations
74
75 ### Podman Connection Plugin Basic Configuration
76
77 ```yaml
78 # inventory.yml
79 [containers]
80 my-container
81
82 [containers:vars]
83 ansible_connection=containers.podman.podman
84 ansible_host=my-container-name
85 ```
86
87 ## Buildah Connection Plugin
88
89 The Buildah connection plugin (`containers.podman.buildah`) enables Ansible to execute tasks inside Buildah working containers, perfect for container image building and customization.
90
91 ### Buildah Connection Plugin Features
92
93 - **Working container management**: Execute tasks in Buildah working containers
94 - **Auto-commit functionality**: Optionally commit changes after task execution
95 - **Working directory support**: Set and manage working directories
96 - **Layer optimization**: Efficient layer creation during image building
97 - **Build context management**: Handle build contexts and file transfers
98
99 ### Buildah Connection Plugin Basic Configuration
100
101 ```yaml
102 # inventory.yml
103 [buildah_containers]
104 build-container
105
106 [buildah_containers:vars]
107 ansible_connection=containers.podman.buildah
108 ansible_host=build-container-name
109 ```
110
111 ## Configuration Options
112
113 ### Podman Connection Plugin Options
114
115 | Option | Type | Default | Description |
116 |--------|------|---------|-------------|
117 | `ansible_podman_executable` | string | `podman` | Path to podman executable |
118 | `ansible_podman_timeout` | int | `0` | Command execution timeout in seconds (0 = no timeout) |
119 | `ansible_podman_extra_env` | dict | `{}` | Additional environment variables to inject |
120 | `ansible_podman_mount_detection` | bool | `true` | Enable mount point detection for file operations |
121 | `ansible_podman_ignore_mount_errors` | bool | `true` | Continue without mount if detection fails |
122
123 ### Buildah Connection Plugin Options
124
125 | Option | Type | Default | Description |
126 |--------|------|---------|-------------|
127 | `ansible_buildah_executable` | string | `buildah` | Path to buildah executable |
128 | `ansible_buildah_timeout` | int | `0` | Command execution timeout in seconds (0 = no timeout) |
129 | `ansible_buildah_extra_env` | dict | `{}` | Additional environment variables to inject |
130 | `ansible_buildah_mount_detection` | bool | `true` | Enable mount point detection for file operations |
131 | `ansible_buildah_ignore_mount_errors` | bool | `true` | Continue without mount if detection fails |
132 | `ansible_buildah_auto_commit` | bool | `false` | Automatically commit changes after tasks |
133 | `ansible_buildah_working_directory` | string | | Working directory for command execution |
134
135 ## Simple Usage Examples
136
137 Note: Modules like `package`, `file`, and `copy` require Python inside the target container. For minimal images without Python, prefer `raw`/`command` tasks or delegate host-side operations (for example, `podman cp`). Examples below assume Python is available unless stated otherwise.
138 ### Example 1: Basic Container Management
139
140 ```yaml
141 ---
142 - name: Configure web server in container
143 hosts: webserver_container
144 vars:
145 ansible_connection: containers.podman.podman
146 ansible_host: nginx-container
147
148 tasks:
149 - name: Install additional packages
150 package:
151 name: curl
152 state: present
153
154 - name: Create configuration directory
155 file:
156 path: /etc/nginx/conf.d
157 state: directory
158 mode: '0755'
159
160 - name: Copy nginx configuration
161 copy:
162 src: nginx.conf
163 dest: /etc/nginx/conf.d/default.conf
164 mode: '0644'
165 notify: restart nginx
166
167 handlers:
168 - name: restart nginx
169 service:
170 name: nginx
171 state: restarted
172 ```
173
174 ### Example 2: Multi-Container Application
175
176 ```yaml
177 ---
178 - name: Deploy multi-tier application
179 hosts: localhost
180 gather_facts: false
181
182 tasks:
183 - name: Start database container
184 containers.podman.podman_container:
185 name: app-database
186 image: postgres:13
187 state: started
188 env:
189 POSTGRES_DB: myapp
190 POSTGRES_USER: appuser
191 POSTGRES_PASSWORD: secret
192 ports:
193 - "5432:5432"
194
195 - name: Start application container
196 containers.podman.podman_container:
197 name: app-server
198 image: python:3.9
199 state: started
200 command: sleep infinity
201 ports:
202 - "8080:8080"
203
204 - name: Configure database
205 hosts: app-database
206 vars:
207 ansible_connection: containers.podman.podman
208 ansible_host: app-database
209
210 tasks:
211 - name: Create application database
212 postgresql_db:
213 name: myapp
214 state: present
215
216 - name: Configure application
217 hosts: app-server
218 vars:
219 ansible_connection: containers.podman.podman
220 ansible_host: app-server
221
222 tasks:
223 - name: Install application dependencies
224 pip:
225 requirements: /app/requirements.txt
226
227 - name: Start application service
228 shell: |
229 cd /app
230 python app.py
231 async: 3600
232 poll: 0
233 ```
234
235 ### Example 3: Simple Image Building with Buildah
236
237 ```yaml
238 ---
239 - name: Build custom image with Buildah
240 hosts: localhost
241 gather_facts: false
242
243 tasks:
244 - name: Create working container
245 shell: buildah from --name custom-build alpine:latest
246
247 - name: Configure the image
248 hosts: custom-build
249 vars:
250 ansible_connection: containers.podman.buildah
251 ansible_host: custom-build
252 ansible_buildah_auto_commit: true
253
254 tasks:
255 - name: Update package index
256 apk:
257 update_cache: true
258
259 - name: Install required packages
260 apk:
261 name:
262 - python3
263 - py3-pip
264 - curl
265 state: present
266
267 - name: Create application user
268 user:
269 name: appuser
270 shell: /bin/sh
271 home: /app
272 create_home: true
273
274 - name: Set working directory
275 file:
276 path: /app
277 state: directory
278 owner: appuser
279 group: appuser
280
281 - name: Commit custom image with Buildah
282 hosts: localhost
283 gather_facts: false
284
285 tasks:
286 - name: Commit the image
287 shell: buildah commit custom-build custom-alpine:latest
288
289 - name: Clean up working container
290 shell: buildah rm custom-build
291 ```
292
293 ## Advanced Usage Examples
294
295 ### Example 1: High-Performance Web Application Deployment
296
297 ```yaml
298 ---
299 - name: Deploy high-performance web application
300 hosts: localhost
301 gather_facts: false
302 vars:
303 app_replicas: 3
304 load_balancer_image: "nginx:alpine"
305 app_image: "python:3.9-slim"
306
307 tasks:
308 - name: Create application network
309 containers.podman.podman_network:
310 name: app-network
311 state: present
312
313 - name: Start application containers
314 containers.podman.podman_container:
315 name: "app-{{ item }}"
316 image: "{{ app_image }}"
317 state: started
318 command: sleep infinity
319 networks:
320 - name: app-network
321 env:
322 FLASK_ENV: production
323 WORKERS: "4"
324 PORT: "5000"
325 healthcheck:
326 test: ["CMD", "curl", "-f", "http://localhost:5000/health"]
327 interval: 30s
328 timeout: 10s
329 retries: 3
330 loop: "{{ range(1, app_replicas + 1) | list }}"
331
332 - name: Start load balancer
333 containers.podman.podman_container:
334 name: load-balancer
335 image: "{{ load_balancer_image }}"
336 state: started
337 ports:
338 - "80:80"
339 - "443:443"
340 networks:
341 - name: app-network
342 volumes:
343 - nginx-config:/etc/nginx/conf.d:ro
344 - ssl-certs:/etc/ssl/certs:ro
345
346 - name: Configure application containers
347 hosts: app_containers
348 vars:
349 ansible_connection: containers.podman.podman
350 ansible_podman_extra_env:
351 PYTHONPATH: "/app"
352 LOG_LEVEL: "INFO"
353 ansible_podman_timeout: 60
354
355 tasks:
356 - name: Install system dependencies
357 apt:
358 name:
359 - build-essential
360 - python3-dev
361 - libpq-dev
362 state: present
363 update_cache: true
364
365 - name: Create application directory structure
366 file:
367 path: "{{ item }}"
368 state: directory
369 mode: '0755'
370 loop:
371 - /app
372 - /app/logs
373 - /app/static
374 - /app/templates
375
376 - name: Copy application code
377 copy:
378 src: "{{ item.src }}"
379 dest: "{{ item.dest }}"
380 mode: "{{ item.mode | default('0644') }}"
381 loop:
382 - { src: "app.py", dest: "/app/app.py", mode: "0755" }
383 - { src: "requirements.txt", dest: "/app/requirements.txt" }
384 - { src: "config.py", dest: "/app/config.py" }
385 - { src: "wsgi.py", dest: "/app/wsgi.py" }
386 notify: restart application
387
388 - name: Install Python dependencies
389 pip:
390 requirements: /app/requirements.txt
391 virtualenv: /app/venv
392 virtualenv_python: python3
393
394 - name: Configure application settings
395 template:
396 src: app_config.j2
397 dest: /app/.env
398 mode: '0600'
399 notify: restart application
400
401 - name: Set up log rotation
402 copy:
403 content: |
404 /app/logs/*.log {
405 daily
406 missingok
407 rotate 30
408 compress
409 delaycompress
410 notifempty
411 copytruncate
412 }
413 dest: /etc/logrotate.d/app
414 mode: '0644'
415
416 - name: Start application with gunicorn
417 shell: |
418 cd /app
419 source venv/bin/activate
420 gunicorn --bind 0.0.0.0:5000 --workers 4 wsgi:app
421 async: 3600
422 poll: 0
423 register: app_service
424
425 handlers:
426 - name: restart application
427 shell: pkill -f gunicorn || true
428
429 - name: Configure load balancer
430 hosts: load-balancer
431 vars:
432 ansible_connection: containers.podman.podman
433 ansible_podman_timeout: 30
434
435 tasks:
436 - name: Generate nginx upstream configuration
437 template:
438 src: nginx_upstream.conf.j2
439 dest: /etc/nginx/conf.d/upstream.conf
440 mode: '0644'
441 notify: reload nginx
442
443 - name: Configure SSL certificates
444 copy:
445 src: "{{ item.src }}"
446 dest: "{{ item.dest }}"
447 mode: '0600'
448 loop:
449 - { src: "ssl/app.crt", dest: "/etc/ssl/certs/app.crt" }
450 - { src: "ssl/app.key", dest: "/etc/ssl/private/app.key" }
451 notify: reload nginx
452
453 - name: Configure nginx main site
454 template:
455 src: nginx_site.conf.j2
456 dest: /etc/nginx/conf.d/default.conf
457 mode: '0644'
458 notify: reload nginx
459
460 handlers:
461 - name: reload nginx
462 service:
463 name: nginx
464 state: reloaded
465 ```
466
467 ### Example 2: Advanced Image Building Pipeline
468
469 ```yaml
470 ---
471 - name: Advanced container image building pipeline
472 hosts: localhost
473 gather_facts: false
474 vars:
475 base_image: "alpine:3.18"
476 build_args:
477 VERSION: "1.0.0"
478 BUILD_DATE: "{{ ansible_date_time.iso8601 }}"
479 COMMIT_SHA: "{{ lookup('env', 'GITHUB_SHA') | default('local') }}"
480
481 tasks:
482 - name: Create build context directory
483 file:
484 path: "{{ item }}"
485 state: directory
486 mode: '0755'
487 loop:
488 - /tmp/build-context
489 - /tmp/build-context/src
490 - /tmp/build-context/config
491 - /tmp/build-context/scripts
492
493 - name: Copy build files
494 copy:
495 src: "{{ item.src }}"
496 dest: "{{ item.dest }}"
497 mode: "{{ item.mode | default('0644') }}"
498 loop:
499 - { src: "src/", dest: "/tmp/build-context/src/", mode: "0755" }
500 - { src: "config/", dest: "/tmp/build-context/config/" }
501 - { src: "scripts/", dest: "/tmp/build-context/scripts/", mode: "0755" }
502 - { src: "requirements.txt", dest: "/tmp/build-context/" }
503 - { src: "Dockerfile", dest: "/tmp/build-context/" }
504
505 - name: Create multi-stage build containers
506 shell: |
507 buildah from --name build-stage {{ base_image }}
508 buildah from --name runtime-stage {{ base_image }}
509 register: build_containers
510
511 - name: Mount build context
512 shell: |
513 buildah copy build-stage /tmp/build-context /build
514 buildah config --workingdir /build build-stage
515
516 - name: Configure build stage
517 hosts: build-stage
518 vars:
519 ansible_connection: containers.podman.buildah
520 ansible_host: build-stage
521 ansible_buildah_working_dir: /build
522 ansible_buildah_extra_env:
523 BUILD_MODE: "production"
524 PYTHONPATH: "/build/src"
525 ansible_buildah_timeout: 300
526
527 tasks:
528 - name: Install build dependencies
529 apk:
530 name:
531 - python3
532 - py3-pip
533 - python3-dev
534 - gcc
535 - musl-dev
536 - libffi-dev
537 - openssl-dev
538 - make
539 - git
540 state: present
541 update_cache: true
542
543 - name: Create virtual environment
544 shell: python3 -m venv /build/venv
545
546 - name: Upgrade pip and install build tools
547 pip:
548 name:
549 - pip
550 - wheel
551 - setuptools
552 state: latest
553 virtualenv: /build/venv
554
555 - name: Install Python dependencies
556 pip:
557 requirements: /build/requirements.txt
558 virtualenv: /build/venv
559
560 - name: Compile application
561 shell: |
562 source /build/venv/bin/activate
563 python setup.py build_ext --inplace
564 python -m compileall src/
565 args:
566 chdir: /build
567
568 - name: Run tests
569 shell: |
570 source /build/venv/bin/activate
571 python -m pytest tests/ -v
572 args:
573 chdir: /build
574
575 - name: Create distribution package
576 shell: |
577 source /build/venv/bin/activate
578 python setup.py sdist bdist_wheel
579 args:
580 chdir: /build
581
582 - name: Prepare runtime artifacts
583 shell: |
584 mkdir -p /build/runtime-artifacts
585 cp -r src/ /build/runtime-artifacts/
586 cp -r venv/ /build/runtime-artifacts/
587 cp requirements.txt /build/runtime-artifacts/
588 cp scripts/entrypoint.sh /build/runtime-artifacts/
589 args:
590 chdir: /build
591
592 - name: Configure runtime stage
593 hosts: runtime-stage
594 vars:
595 ansible_connection: containers.podman.buildah
596 ansible_host: runtime-stage
597 ansible_buildah_working_dir: /app
598 ansible_buildah_extra_env:
599 PYTHONPATH: "/app/src"
600 FLASK_ENV: "production"
601 ansible_buildah_auto_commit: false
602
603 tasks:
604 - name: Install runtime dependencies only
605 apk:
606 name:
607 - python3
608 - py3-pip
609 - curl
610 - ca-certificates
611 state: present
612 update_cache: true
613
614 - name: Create application user
615 user:
616 name: appuser
617 shell: /bin/sh
618 home: /app
619 create_home: true
620 system: true
621
622 - name: Create application directories
623 file:
624 path: "{{ item }}"
625 state: directory
626 owner: appuser
627 group: appuser
628 mode: '0755'
629 loop:
630 - /app
631 - /app/logs
632 - /app/data
633 - /app/tmp
634
635 - name: Copy runtime artifacts from build stage
636 shell: |
637 buildah copy --from build-stage runtime-stage /build/runtime-artifacts /app
638
639 - name: Set proper ownership
640 file:
641 path: /app
642 owner: appuser
643 group: appuser
644 recurse: true
645
646 - name: Configure entrypoint
647 shell: |
648 buildah config --user appuser runtime-stage
649 buildah config --workingdir /app runtime-stage
650 buildah config --entrypoint '["./entrypoint.sh"]' runtime-stage
651 buildah config --cmd '["python", "src/app.py"]' runtime-stage
652
653 - name: Set labels
654 shell: |
655 buildah config --label version="{{ build_args.VERSION }}" runtime-stage
656 buildah config --label build-date="{{ build_args.BUILD_DATE }}" runtime-stage
657 buildah config --label commit-sha="{{ build_args.COMMIT_SHA }}" runtime-stage
658 buildah config --label maintainer="DevOps Team" runtime-stage
659
660 - name: Configure health check
661 shell: |
662 buildah config --healthcheck 'CMD curl -f http://localhost:5000/health || exit 1' runtime-stage
663 buildah config --healthcheck-interval 30s runtime-stage
664 buildah config --healthcheck-timeout 10s runtime-stage
665 buildah config --healthcheck-retries 3 runtime-stage
666
667 - name: Finalize and tag image
668 hosts: localhost
669 gather_facts: false
670
671 tasks:
672 - name: Commit final image
673 shell: |
674 buildah commit runtime-stage myapp:{{ build_args.VERSION }}
675 buildah commit runtime-stage myapp:latest
676
677 - name: Tag for registry
678 shell: |
679 buildah tag myapp:{{ build_args.VERSION }} registry.example.com/myapp:{{ build_args.VERSION }}
680 buildah tag myapp:latest registry.example.com/myapp:latest
681 when: lookup('env', 'REGISTRY_PUSH') == 'true'
682
683 - name: Push to registry
684 shell: |
685 buildah push registry.example.com/myapp:{{ build_args.VERSION }}
686 buildah push registry.example.com/myapp:latest
687 when: lookup('env', 'REGISTRY_PUSH') == 'true'
688
689 - name: Clean up build containers
690 shell: |
691 buildah rm build-stage runtime-stage
692
693 - name: Clean up build context
694 file:
695 path: /tmp/build-context
696 state: absent
697
698 - name: Display image information
699 shell: podman inspect myapp:{{ build_args.VERSION }}
700 register: image_info
701
702 - name: Show build summary
703 debug:
704 msg: |
705 Build completed successfully!
706 Image: myapp:{{ build_args.VERSION }}
707 Size: {{ (image_info.stdout | from_json)[0].Size | human_readable }}
708 Created: {{ (image_info.stdout | from_json)[0].Created }}
709 Labels: {{ (image_info.stdout | from_json)[0].Config.Labels }}
710 ```
711
712 ### Example 3: Container Development Environment
713
714 ```yaml
715 ---
716 - name: Set up development environment
717 hosts: localhost
718 gather_facts: false
719 vars:
720 dev_containers:
721 - name: dev-database
722 image: postgres:13
723 ports: ["5432:5432"]
724 env:
725 POSTGRES_DB: devdb
726 POSTGRES_USER: developer
727 POSTGRES_PASSWORD: devpass
728 - name: dev-redis
729 image: redis:alpine
730 ports: ["6379:6379"]
731 - name: dev-workspace
732 image: ubuntu:22.04
733 command: sleep infinity
734 ports: ["8080:8080", "3000:3000"]
735 volumes:
736 - "${PWD}:/workspace"
737
738 tasks:
739 - name: Create development network
740 containers.podman.podman_network:
741 name: dev-network
742 state: present
743
744 - name: Start development containers
745 containers.podman.podman_container:
746 name: "{{ item.name }}"
747 image: "{{ item.image }}"
748 state: started
749 command: "{{ item.command | default(omit) }}"
750 ports: "{{ item.ports | default([]) }}"
751 env: "{{ item.env | default({}) }}"
752 volumes: "{{ item.volumes | default([]) }}"
753 networks:
754 - name: dev-network
755 loop: "{{ dev_containers }}"
756
757 - name: Configure development workspace
758 hosts: dev-workspace
759 vars:
760 ansible_connection: containers.podman.podman
761 ansible_host: dev-workspace
762 ansible_podman_extra_env:
763 TERM: "xterm-256color"
764 EDITOR: "vim"
765 ansible_podman_timeout: 120
766
767 tasks:
768 - name: Update package cache
769 apt:
770 update_cache: true
771
772 - name: Install development tools
773 apt:
774 name:
775 - curl
776 - wget
777 - git
778 - vim
779 - tmux
780 - zsh
781 - python3
782 - python3-pip
783 - nodejs
784 - npm
785 - build-essential
786 - postgresql-client
787 - redis-tools
788 state: present
789
790 - name: Install Python development packages
791 pip:
792 name:
793 - ipython
794 - jupyter
795 - black
796 - flake8
797 - pytest
798 - requests
799 - sqlalchemy
800 - redis
801 state: present
802
803 - name: Configure Git
804 git_config:
805 name: "{{ item.name }}"
806 value: "{{ item.value }}"
807 scope: global
808 loop:
809 - { name: "user.name", value: "Developer" }
810 - { name: "user.email", value: "[email protected]" }
811 - { name: "init.defaultBranch", value: "main" }
812
813 - name: Set up shell environment
814 copy:
815 content: |
816 export PATH=$PATH:/workspace/bin
817 export PYTHONPATH=/workspace/src
818 export DATABASE_URL=postgresql://developer:devpass@dev-database:5432/devdb
819 export REDIS_URL=redis://dev-redis:6379/0
820
821 alias ll='ls -la'
822 alias ..='cd ..'
823 alias gs='git status'
824 alias gd='git diff'
825 alias gc='git commit'
826 alias gp='git push'
827
828 # Auto-activate virtual environment if it exists
829 if [ -d "/workspace/venv" ]; then
830 source /workspace/venv/bin/activate
831 fi
832 dest: /root/.bashrc
833 mode: '0644'
834
835 - name: Create workspace directories
836 file:
837 path: "{{ item }}"
838 state: directory
839 mode: '0755'
840 loop:
841 - /workspace/src
842 - /workspace/tests
843 - /workspace/docs
844 - /workspace/bin
845 - /workspace/config
846
847 - name: Install oh-my-zsh
848 shell: |
849 sh -c "$(curl -fsSL https://raw.github.com/ohmyzsh/ohmyzsh/master/tools/install.sh)" || true
850 chsh -s $(which zsh)
851 ignore_errors: true
852
853 - name: Start Jupyter notebook server
854 shell: |
855 cd /workspace
856 nohup jupyter notebook --ip=0.0.0.0 --port=8080 --no-browser --allow-root &
857 async: 10
858 poll: 0
859 ignore_errors: true
860
861 - name: Verify development environment
862 hosts: localhost
863 gather_facts: false
864
865 tasks:
866 - name: Test database connection
867 shell: |
868 podman exec dev-workspace psql postgresql://developer:devpass@dev-database:5432/devdb -c "SELECT version();"
869 register: db_test
870 ignore_errors: true
871
872 - name: Test Redis connection
873 shell: |
874 podman exec dev-workspace redis-cli -h dev-redis ping
875 register: redis_test
876 ignore_errors: true
877
878 - name: Display environment status
879 debug:
880 msg: |
881 Development environment ready!
882
883 Services:
884 - Database: {{ 'OK' if db_test.rc == 0 else 'FAILED' }}
885 - Redis: {{ 'OK' if redis_test.rc == 0 else 'FAILED' }}
886 - Workspace: Running
887
888 Access:
889 - Jupyter: http://localhost:8080
890 - Workspace: podman exec -it dev-workspace /bin/bash
891 - Database: psql postgresql://developer:devpass@localhost:5432/devdb
892
893 Workspace mounted at: /workspace
894 ```
895
896 ## Performance and Best Practices
897
898 ### Connection Caching
899
900 Both plugins internally cache lightweight details (for example, container validation) to reduce overhead. There are no user-facing options to control this.
901
902 ### Mount Detection
903
904 Enable mount detection for efficient file transfers:
905
906 ```yaml
907 # Automatically detect shared mounts (default: true)
908 ansible_podman_mount_detection: true
909 ansible_buildah_mount_detection: true
910
911 # Ignore mount detection errors
912 ansible_podman_ignore_mount_errors: true
913 ansible_buildah_ignore_mount_errors: true
914 ```
915
916 ### Timeout Configuration
917
918 Configure optional timeouts (default is 0 = no timeout):
919
920 ```yaml
921 # Command timeout in seconds (0 = no timeout)
922 ansible_podman_timeout: 0
923 ansible_buildah_timeout: 0
924 ```
925
926 ### Environment Variable Management
927
928 Efficiently pass environment variables:
929
930 ```yaml
931 # Method 1: Individual variables
932 ansible_podman_extra_env:
933 API_KEY: "{{ vault_api_key }}"
934 DEBUG: "true"
935 LOG_LEVEL: "INFO"
936
937 # Method 2: From file
938 ansible_podman_extra_env: "{{ lookup('file', 'env.json') | from_json }}"
939 ```
940
941 ### Best Practices
942
943 1. **Use specific container names**: Avoid generic names to prevent conflicts
944 2. **Implement health checks**: Use container health checks for reliability
945 3. **Handle secrets securely**: Use Ansible Vault for sensitive data
946 4. **Monitor resource usage**: Set appropriate memory and CPU limits
947 5. **Use multi-stage builds**: Optimize image size with Buildah multi-stage builds
948 6. **Cache dependencies**: Leverage layer caching for faster builds
949 7. **Design for fail-fast**: Prefer explicit failed_when/changed_when instead of retries
950
951 ## Troubleshooting
952
953 ### Common Issues
954
955 #### Container Not Found
956
957 ```text
958 Error: Container 'my-container' not found
959 ```
960
961 **Solution**: Ensure the container is running and the name/ID is correct.
962
963 #### Permission Denied
964
965 ```text
966 Error: Permission denied when accessing container
967 ```
968
969 **Solution**: Check container permissions or run with appropriate privileges.
970
971 #### Timeout Errors
972
973 ```text
974 Error: Command execution timed out
975 ```
976
977 **Solution**: Increase timeout values or optimize commands.
978
979 #### Mount Detection Failures
980
981 ```text
982 Warning: Mount detection failed
983 ```
984
985 **Solution**: Disable mount detection or ignore mount errors.
986
987 ### Debug Configuration
988
989 Enable verbose logging for troubleshooting:
990
991 ```yaml
992 # Enable debug logging
993 ansible_podman_debug: true
994 ansible_buildah_debug: true
995
996 # Increase verbosity
997 ansible_verbosity: 3
998 ```
999
1000 ### Testing Connection
1001
1002 Test connection plugin functionality:
1003
1004 ```bash
1005 # Test Podman connection
1006 ansible -i inventory -m setup podman_host
1007
1008 # Test Buildah connection
1009 ansible -i inventory -m setup buildah_host
1010
1011 # Run connection tests
1012 ./ci/run_connection_test.sh podman
1013 ./ci/run_connection_test.sh buildah
1014 ```
1015
1016 ## Migration from Legacy Plugins
1017
1018 ### From Docker Connection Plugin
1019
1020 Replace Docker connection configuration:
1021
1022 ```yaml
1023 # Old Docker configuration
1024 ansible_connection: docker
1025 ansible_docker_extra_args: "--user root"
1026
1027 # New Podman configuration
1028 ansible_connection: containers.podman.podman
1029 ansible_podman_extra_env:
1030 USER: root
1031 ```
1032
1033 ### From Custom Scripts
1034
1035 Replace custom container execution scripts:
1036
1037 ```yaml
1038 # Old custom script approach
1039 - name: Run in container
1040 shell: podman exec my-container {{ command }}
1041
1042 # New connection plugin approach
1043 - name: Run in container
1044 hosts: my-container
1045 vars:
1046 ansible_connection: containers.podman.podman
1047 tasks:
1048 - name: Execute command
1049 command: "{{ command }}"
1050 ```
1051
1052 ### Configuration Mapping
1053
1054 | Legacy Option | Podman Plugin | Buildah Plugin |
1055 |---------------|---------------|----------------|
1056 | `ansible_docker_extra_args` | `ansible_podman_extra_env` | `ansible_buildah_extra_env` |
1057 | `ansible_docker_timeout` | `ansible_podman_timeout` | `ansible_buildah_timeout` |
1058 | N/A | `ansible_podman_retries` | `ansible_buildah_retries` |
1059 | N/A | `ansible_podman_mount_detection` | `ansible_buildah_mount_detection` |
1060
1061 ---
1062
1063 For more information and examples, see the [official documentation](https://github.com/containers/ansible-podman-collections) and [test cases](tests/integration/targets/).