idem-gcp


Nameidem-gcp JSON
Version 2.2.2 PyPI version JSON
download
home_pagehttps://gitlab.com/vmware/idem/idem-gcp
SummaryGCP Cloud Provider for Idem
upload_time2023-09-05 15:24:13
maintainer
docs_urlNone
authorVMware, Inc.
requires_python>=3.8
licenseApache Software License 2.0
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            ========
idem-gcp
========

.. image:: https://img.shields.io/badge/made%20with-pop-teal
   :alt: Made with pop, a Python implementation of Plugin Oriented Programming
   :target: https://pop.readthedocs.io/

.. image:: https://img.shields.io/badge/made%20with-idem-teal
   :alt: Made with idem, a Python implementation of Plugin Oriented Programming
   :target: https://www.idemproject.io/

.. image:: https://img.shields.io/badge/docs%20on-docs.idemproject.io-blue
   :alt: Documentation is published with Sphinx on docs.idemproject.io
   :target: https://docs.idemproject.io/idem-gcp/en/latest/index.html

.. image:: https://img.shields.io/badge/made%20with-python-yellow
   :alt: Made with Python
   :target: https://www.python.org/

GCP Cloud Provider for Idem.

About
=====

``idem-gcp`` helps manage GCP with ``idem``.

* `idem-gcp source code <https://gitlab.com/vmware/idem/idem-gcp>`__
* `idem-gcp documentation <https://docs.idemproject.io/idem-gcp/en/latest/index.html>`__

What is POP?
------------

This project is built with `pop <https://pop.readthedocs.io/>`__, a Python-based
implementation of *Plugin Oriented Programming (POP)*. POP seeks to bring
together concepts and wisdom from the history of computing in new ways to solve
modern computing problems.

For more information:

* `Intro to Plugin Oriented Programming (POP) <https://pop-book.readthedocs.io/en/latest/>`__
* `pop-awesome <https://gitlab.com/saltstack/pop/pop-awesome>`__
* `pop-create <https://gitlab.com/saltstack/pop/pop-create/>`__

What is Idem?
-------------

This project is built with `idem <https://www.idemproject.io/>`__, an idempotent,
imperatively executed, declarative programming language written in Python. This project extends
idem!

For more information:

* `Idem Project Website <https://www.idemproject.io/>`__
* `Idem Project docs portal <https://docs.idemproject.io/>`__

Getting Started
===============

Prerequisites
-------------

* Python 3.8+
* git *(if installing from source, or contributing to the project)*

Installation
------------

.. note::

   If wanting to contribute to the project, and setup your local development
   environment, see the ``CONTRIBUTING.rst`` document in the source repository
   for this project.

If wanting to use ``idem-gcp``, you can do so by either
installing from PyPI or from source.

Install from PyPI
+++++++++++++++++

.. code-block:: bash

  pip install idem-gcp

Install from source
+++++++++++++++++++

Clone the `idem_gcp` repository.

.. code:: bash

    git clone git@gitlab.com:vmware/idem/idem-gcp.git
    cd idem_gcp

Create a virtual environment, and then activate it:

.. code:: bash

    python3 -m venv venv
    source venv/bin/activate

Install idem-gcp and other base requirements:

.. code:: bash

    pip3 install -e .
    pip3 install -r requirements/base.txt


Install the following packages in order to run the tests:

.. code:: bash

    pip3 install -r requirements/py3.10/tests.txt

**NOTE:**  Change py3.10 if needed with your  Python version. There is support for py3.8, py3.9, py3.10 and py3.11.

Setup
=====

After installation GCP Idem Provider execution and state modules will be accessible to the pop `hub`.
In order to use them we need to set up our credentials.

Create a new file called `credentials.yaml` and populate it with your credential profiles.

To provide your GCP credentials in the file, use the "gcp" provider key.
Under that key, add different profiles as needed.
A profile specifies authentication parameters for GCP.
The `default` profile will be automatically used by `idem`,
but the other ones could be explicitly specified for each run or SLS file.
This is done through the `--acct-profile` `idem` cli flag or the
`acct_profile` SLS property.

There is currently one GCP authentication mechanism supported by idem-gcp -
providing service account keys.
The following example gives the overall structure of the authentication
parameters' expected format.

credentials.yaml

..  code:: sls

    gcp:
      default:
        type: service_account
        project_id: “<project>”
        private_key_id: “<key_id>”
        private_key: "-----BEGIN PRIVATE KEY-----\n<private_key>\n-----END PRIVATE KEY-----\n"
        client_email: “<service_account_email>“
        client_id: “<client_id>”
        auth_uri: https://accounts.google.com/o/oauth2/auth
        token_uri: https://oauth2.googleapis.com/token
        auth_provider_x509_cert_url: https://www.googleapis.com/oauth2/v1/certs
        client_x509_cert_url: “<certificate_url>“
        universe_domain: googleapis.com
      <other_profile_name>:
        ...

The values of these parameters can be obtained through the GCP console after creating a service account and generating a service account key in JSON format.
Be sure to assign appropriate roles for the service account, such that it has the rights to access and manage the needed resources.
For a better security posture, follow the principal of least privilege and do not use service accounts with excessive rights.
For more information on the authentication parameters used, refer to the `Credentials <https://google-auth.readthedocs.io/en/master/reference/google.oauth2.service_account.html#google.oauth2.service_account.Credentials>`_ docs.

Encrypt the created credentials file:


.. code:: bash

    acct encrypt credentials.yaml


The output of this command is the ACCT_KEY which needs to be securely stored.
A `credentials.yaml.fernet` encrypted file is also created in the working directory, whose path should be used as ACCT_FILE.
These could be given to idem either through environment variables or directly as `idem` run parameters.

Setting environment variables
-----------------------------

.. code:: bash

    export ACCT_KEY="<ACCT_KEY>"
    export ACCT_FILE=$PWD/credentials.yaml.fernet

Providing acct parameters to the idem run
-----------------------------------------

.. code:: bash

    idem <subcommand> --acct-key "<ACCT_KEY>" --acct-file "$PWD/credentials.yaml.fernet" --acct-profile "<profile_name>"

Specifying account profile in SLS files
---------------------------------------

.. code:: sls

    ensure_resource:
      gcp.<service>.<resource>.present:
        - acct_profile: <profile_name>
        - name: resource_name
        - kwarg1: val1


For more information on the Idem ACCT authentication management subsystem, refer to the following resources:

* `Account credentials file doc <https://docs.idemproject.io/idem/en/latest/topics/tutorials/acct_file.html>`_
* `Multiple Account Management <https://docs.idemproject.io/idem/en/latest/topics/tutorials/acct.html>`_
* `ACCT advanced features <https://docs.idemproject.io/idem/en/latest/topics/sls_acct.html>`_



            

Raw data

            {
    "_id": null,
    "home_page": "https://gitlab.com/vmware/idem/idem-gcp",
    "name": "idem-gcp",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": "",
    "keywords": "",
    "author": "VMware, Inc.",
    "author_email": "idemproject@vmware.com",
    "download_url": "https://files.pythonhosted.org/packages/67/ea/c9c3356cdcd67542903152137158df2de7ed6b0db01d265c25065379ab26/idem_gcp-2.2.2.tar.gz",
    "platform": null,
    "description": "========\nidem-gcp\n========\n\n.. image:: https://img.shields.io/badge/made%20with-pop-teal\n   :alt: Made with pop, a Python implementation of Plugin Oriented Programming\n   :target: https://pop.readthedocs.io/\n\n.. image:: https://img.shields.io/badge/made%20with-idem-teal\n   :alt: Made with idem, a Python implementation of Plugin Oriented Programming\n   :target: https://www.idemproject.io/\n\n.. image:: https://img.shields.io/badge/docs%20on-docs.idemproject.io-blue\n   :alt: Documentation is published with Sphinx on docs.idemproject.io\n   :target: https://docs.idemproject.io/idem-gcp/en/latest/index.html\n\n.. image:: https://img.shields.io/badge/made%20with-python-yellow\n   :alt: Made with Python\n   :target: https://www.python.org/\n\nGCP Cloud Provider for Idem.\n\nAbout\n=====\n\n``idem-gcp`` helps manage GCP with ``idem``.\n\n* `idem-gcp source code <https://gitlab.com/vmware/idem/idem-gcp>`__\n* `idem-gcp documentation <https://docs.idemproject.io/idem-gcp/en/latest/index.html>`__\n\nWhat is POP?\n------------\n\nThis project is built with `pop <https://pop.readthedocs.io/>`__, a Python-based\nimplementation of *Plugin Oriented Programming (POP)*. POP seeks to bring\ntogether concepts and wisdom from the history of computing in new ways to solve\nmodern computing problems.\n\nFor more information:\n\n* `Intro to Plugin Oriented Programming (POP) <https://pop-book.readthedocs.io/en/latest/>`__\n* `pop-awesome <https://gitlab.com/saltstack/pop/pop-awesome>`__\n* `pop-create <https://gitlab.com/saltstack/pop/pop-create/>`__\n\nWhat is Idem?\n-------------\n\nThis project is built with `idem <https://www.idemproject.io/>`__, an idempotent,\nimperatively executed, declarative programming language written in Python. This project extends\nidem!\n\nFor more information:\n\n* `Idem Project Website <https://www.idemproject.io/>`__\n* `Idem Project docs portal <https://docs.idemproject.io/>`__\n\nGetting Started\n===============\n\nPrerequisites\n-------------\n\n* Python 3.8+\n* git *(if installing from source, or contributing to the project)*\n\nInstallation\n------------\n\n.. note::\n\n   If wanting to contribute to the project, and setup your local development\n   environment, see the ``CONTRIBUTING.rst`` document in the source repository\n   for this project.\n\nIf wanting to use ``idem-gcp``, you can do so by either\ninstalling from PyPI or from source.\n\nInstall from PyPI\n+++++++++++++++++\n\n.. code-block:: bash\n\n  pip install idem-gcp\n\nInstall from source\n+++++++++++++++++++\n\nClone the `idem_gcp` repository.\n\n.. code:: bash\n\n    git clone git@gitlab.com:vmware/idem/idem-gcp.git\n    cd idem_gcp\n\nCreate a virtual environment, and then activate it:\n\n.. code:: bash\n\n    python3 -m venv venv\n    source venv/bin/activate\n\nInstall idem-gcp and other base requirements:\n\n.. code:: bash\n\n    pip3 install -e .\n    pip3 install -r requirements/base.txt\n\n\nInstall the following packages in order to run the tests:\n\n.. code:: bash\n\n    pip3 install -r requirements/py3.10/tests.txt\n\n**NOTE:**  Change py3.10 if needed with your  Python version. There is support for py3.8, py3.9, py3.10 and py3.11.\n\nSetup\n=====\n\nAfter installation GCP Idem Provider execution and state modules will be accessible to the pop `hub`.\nIn order to use them we need to set up our credentials.\n\nCreate a new file called `credentials.yaml` and populate it with your credential profiles.\n\nTo provide your GCP credentials in the file, use the \"gcp\" provider key.\nUnder that key, add different profiles as needed.\nA profile specifies authentication parameters for GCP.\nThe `default` profile will be automatically used by `idem`,\nbut the other ones could be explicitly specified for each run or SLS file.\nThis is done through the `--acct-profile` `idem` cli flag or the\n`acct_profile` SLS property.\n\nThere is currently one GCP authentication mechanism supported by idem-gcp -\nproviding service account keys.\nThe following example gives the overall structure of the authentication\nparameters' expected format.\n\ncredentials.yaml\n\n..  code:: sls\n\n    gcp:\n      default:\n        type: service_account\n        project_id: \u201c<project>\u201d\n        private_key_id: \u201c<key_id>\u201d\n        private_key: \"-----BEGIN PRIVATE KEY-----\\n<private_key>\\n-----END PRIVATE KEY-----\\n\"\n        client_email: \u201c<service_account_email>\u201c\n        client_id: \u201c<client_id>\u201d\n        auth_uri: https://accounts.google.com/o/oauth2/auth\n        token_uri: https://oauth2.googleapis.com/token\n        auth_provider_x509_cert_url: https://www.googleapis.com/oauth2/v1/certs\n        client_x509_cert_url: \u201c<certificate_url>\u201c\n        universe_domain: googleapis.com\n      <other_profile_name>:\n        ...\n\nThe values of these parameters can be obtained through the GCP console after creating a service account and generating a service account key in JSON format.\nBe sure to assign appropriate roles for the service account, such that it has the rights to access and manage the needed resources.\nFor a better security posture, follow the principal of least privilege and do not use service accounts with excessive rights.\nFor more information on the authentication parameters used, refer to the `Credentials <https://google-auth.readthedocs.io/en/master/reference/google.oauth2.service_account.html#google.oauth2.service_account.Credentials>`_ docs.\n\nEncrypt the created credentials file:\n\n\n.. code:: bash\n\n    acct encrypt credentials.yaml\n\n\nThe output of this command is the ACCT_KEY which needs to be securely stored.\nA `credentials.yaml.fernet` encrypted file is also created in the working directory, whose path should be used as ACCT_FILE.\nThese could be given to idem either through environment variables or directly as `idem` run parameters.\n\nSetting environment variables\n-----------------------------\n\n.. code:: bash\n\n    export ACCT_KEY=\"<ACCT_KEY>\"\n    export ACCT_FILE=$PWD/credentials.yaml.fernet\n\nProviding acct parameters to the idem run\n-----------------------------------------\n\n.. code:: bash\n\n    idem <subcommand> --acct-key \"<ACCT_KEY>\" --acct-file \"$PWD/credentials.yaml.fernet\" --acct-profile \"<profile_name>\"\n\nSpecifying account profile in SLS files\n---------------------------------------\n\n.. code:: sls\n\n    ensure_resource:\n      gcp.<service>.<resource>.present:\n        - acct_profile: <profile_name>\n        - name: resource_name\n        - kwarg1: val1\n\n\nFor more information on the Idem ACCT authentication management subsystem, refer to the following resources:\n\n* `Account credentials file doc <https://docs.idemproject.io/idem/en/latest/topics/tutorials/acct_file.html>`_\n* `Multiple Account Management <https://docs.idemproject.io/idem/en/latest/topics/tutorials/acct.html>`_\n* `ACCT advanced features <https://docs.idemproject.io/idem/en/latest/topics/sls_acct.html>`_\n\n\n",
    "bugtrack_url": null,
    "license": "Apache Software License 2.0",
    "summary": "GCP Cloud Provider for Idem",
    "version": "2.2.2",
    "project_urls": {
        "Code": "https://gitlab.com/vmware/idem/idem-gcp",
        "Homepage": "https://gitlab.com/vmware/idem/idem-gcp",
        "Issue tracker": "https://gitlab.com/vmware/idem/idem-gcp/-/issues"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "pypi",
            "digests": {
                "blake2b_256": "8fd99fc4f3386381d8975857916b1b2de212d43cefc0420d7ef56ac6358071f9",
                "md5": "e7aea5760618a4ade99f76fc217f0f77",
                "sha256": "af00ce07dd5dd645c42e765c38f783edaf10efab125a0f16eea3d09e5b56adff"
            },
            "downloads": -1,
            "filename": "idem_gcp-2.2.2-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "e7aea5760618a4ade99f76fc217f0f77",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 283718,
            "upload_time": "2023-09-05T15:24:11",
            "upload_time_iso_8601": "2023-09-05T15:24:11.387463Z",
            "url": "https://files.pythonhosted.org/packages/8f/d9/9fc4f3386381d8975857916b1b2de212d43cefc0420d7ef56ac6358071f9/idem_gcp-2.2.2-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "pypi",
            "digests": {
                "blake2b_256": "67eac9c3356cdcd67542903152137158df2de7ed6b0db01d265c25065379ab26",
                "md5": "f362bb8b77b72cc2d02d53cbdf87fb48",
                "sha256": "55b2e313211c6a76315e995e217f619b71b4ed33ac4fadf5968af89d34badc21"
            },
            "downloads": -1,
            "filename": "idem_gcp-2.2.2.tar.gz",
            "has_sig": false,
            "md5_digest": "f362bb8b77b72cc2d02d53cbdf87fb48",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 190551,
            "upload_time": "2023-09-05T15:24:13",
            "upload_time_iso_8601": "2023-09-05T15:24:13.659522Z",
            "url": "https://files.pythonhosted.org/packages/67/ea/c9c3356cdcd67542903152137158df2de7ed6b0db01d265c25065379ab26/idem_gcp-2.2.2.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-09-05 15:24:13",
    "github": false,
    "gitlab": true,
    "bitbucket": false,
    "codeberg": false,
    "gitlab_user": "vmware",
    "gitlab_project": "idem",
    "lcname": "idem-gcp"
}
        
Elapsed time: 0.16343s