Omgaan met PIP-fout voor extern beheerde omgeving

Probleem

Op Ubuntu 24.04 leidt een poging om Python-pakketten globaal te installeren met pip3 vaak tot een fout ’externally-managed-environment’. Dit voorkomt de directe installatie van pakketten die nodig zijn voor Ansible-modules, zoals pyOpenSSL of python-gitlab, en verstoort automatiseringsworkflows zoals het bootstrappen van VM’s met noodzakelijke afhankelijkheden.

Context

Ubuntu 24.04 handhaaft strengere pakketbeheerregels om de systeembestendigheid te behouden, zoals beschreven in PEP 668. Dit beschermt de systeem-Python-omgeving tegen conflicten veroorzaakt door door gebruikers geïnstalleerde pakketten. In Ansible-projecten beïnvloedt dit taken die Python-afhankelijkheden installeren voor collecties zoals community.crypto of community.general. Hoewel sommige pakketten OS-niveau-equivalenten hebben (bijv. python3-openssl), hebben anderen dat niet, wat alternatieve benaderingen vereist zoals virtuele omgevingen om compatibiliteit en beveiliging te waarborgen.

Oplossing

Om deze fout op te lossen, volg een gestructureerde benadering die prioriteit geeft aan systeemintegriteit en beste praktijken voor Python-pakketbeheer in Ansible-automatisering.

Volg deze richtlijnen:

1. Zoek naar OS-equivalente pakketten: Voordat je installeert via pip, controleer op Debian-gepakte versies met apt search python3- of apt list | grep python3-. Installeer ze indien beschikbaar (bijv. apt install python3-lxml). Dit vermijdt de fout en integreert met het pakketbeheersysteem van het systeem.

2. Gebruik virtuele omgevingen voor niet-Debian-pakketten: Voor pakketten zonder OS-equivalenten (bijv. python-gitlab), maak een virtuele omgeving:

   • Installeer vereisten: apt install python3-venv python3-full.
   • Maak en activeer: python3 -m venv /path/to/venv en source /path/to/venv/bin/activate.
   • Installeer pakketten in de venv: pip install python-gitlab.
   • Configureer Ansible om deze venv te gebruiken door de variabele ansible_python_interpreter in te stellen in je inventarisproject of playbook om te verwijzen naar de Python-binary van de venv.

3. Bootstrap virtuele omgevingen met Ansible: Om de creatie van venv te automatiseren, gebruik een speciale bootstrap-playbook die eerst draait op de systeem-Python:

   • Maak een playbook om de venv in te stellen en afhankelijkheden te installeren.
   • Voer het uit met de standaard Python-interpreter.
   • Volgende playbooks kunnen dan de interpreter van de venv specificeren via ansible_python_interpreter in groepsvariabelen of hostvariabelen.
   • Dit maakt het mogelijk om interpreters te wisselen tijdens uitvoering indien nodig, maar voor duidelijkheid, scheid bootstrapping in een eigen play of playbook.

4. Organisatiebrede VM-templates (aanbevolen op lange termijn): Pleit voor vooraf geconfigureerde VM-templates die een standaard virtuele omgeving bevatten die is afgestemd op Ansible. Dit zorgt voor consistentie over uitrollen heen, maar kan coördinatie met infrastructuurteams vereisen.

5. Snelle oplossing met voorzichtigheid: Als laatste redmiddel, gebruik --break-system-packages (bijv. pip3 install --break-system-packages python-gitlab). Dit overschrijft de fout maar brengt risico’s voor systeemonstabiliteit met zich mee—vermijd in productie en monitor op conflicten.

Voordelen

• Systeembestendigheid: Geeft voorkeur aan native pakketten en geïsoleerde omgevingen om conflicten met de OS-Python te voorkomen.
• Automatiseringsvriendelijk: Maakt naadloze integratie met Ansible mogelijk voor reproduceerbare setups.
• Schaalbaarheid: VM-templates en bootstrap-playbooks bevorderen consistentie over teams en omgevingen heen.
• Beveiliging: Vermindert risico’s door globale wijzigingen te vermijden tenzij noodzakelijk.

Alternatieven

Direct wijzigen van systeem-Python-bestanden (bijv. verwijderen van markeringen) wordt sterk afgeraden omdat het kan leiden tot onbeheersbare setups. Tools zoals pipx zijn geschikt voor toepassingen maar minder ideaal voor Ansible-module-afhankelijkheden; virtuele omgevingen hebben de voorkeur vanwege hun flexibiliteit in automatiseringscontexten.

Voorbeelden en implementatie

De fout verschijnt vaak tijdens Ansible-bootstrap-taken:

root@pxd-ubuntu-devtop:~# pip3 install python-gitlab
error: externally-managed-environment

× This environment is externally managed
╰─> To install Python packages system-wide, try apt install
    python3-xyz, where xyz is the package you are trying to
    install.

    If you wish to install a non-Debian-packaged Python package,
    create a virtual environment using python3 -m venv path/to/venv.
    Then use path/to/venv/bin/python and path/to/venv/bin/pip. Make
    sure you have python3-full installed.

    If you wish to install a non-Debian packaged Python application,
    it may be easiest to use pipx install xyz, which will manage a
    virtual environment for you. Make sure you have pipx installed.

    See /usr/share/doc/python3.12/README.venv for more information.

note: If you believe this is a mistake, please contact your Python installation or OS distribution provider. You can override this, at the risk of breaking your Python installation or OS, by passing --break-system-packages.
hint: See PEP 668 for the detailed specification.

Reproduceer op de command line:

root@pxd-ubuntu-devtop:~# pip3 install python-gitlab
error: externally-managed-environment
...
hint: See PEP 668 for the detailed specification.

Voorbeeld van pakketmapping (niet uitputtend):

Voorbeeld van het gebruikt van --break-system-packages in combinatie met een C2 Platform resources-variabele:

 group_vars/gitlab/projects.yml

1---
2gitlab_resources:
3  1_api_config:  #  → gitlab_resource_groups_disabled
4    - name: python-gitlab
5      module: pip
6      extra_args: --break-system-packages

Voor Ansible-bootstrapping met venvs:

• Bootstrap-playbook gebruikt systeem-Python om venv te maken.
• Hoofdplaybooks verwijzen naar de venv: ansible_python_interpreter: /path/to/venv/bin/python3.

Dit zorgt ervoor dat Ansible zonder problemen interpreters kan wisselen tijdens uitvoering.

Aanvullende informatie

• PEP 668 - Het markeren van Python-base-omgevingen als extern beheerd