Tower: upload cetmix_tower_aws 18.0.1.0.1 (was 18.0.1.0.1, via marketplace)
This commit is contained in:
308
addons/cetmix_tower_aws/README.rst
Normal file
308
addons/cetmix_tower_aws/README.rst
Normal file
@@ -0,0 +1,308 @@
|
||||
================
|
||||
Cetmix Tower AWS
|
||||
================
|
||||
|
||||
..
|
||||
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
||||
!! This file is generated by oca-gen-addon-readme !!
|
||||
!! changes will be overwritten. !!
|
||||
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
||||
!! source digest: sha256:e427fa4368b78aacbc6faa6232b54496e83fbe4905ddef4cc17f3913e5ee3ee0
|
||||
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
|
||||
|
||||
.. |badge1| image:: https://img.shields.io/badge/maturity-Beta-yellow.png
|
||||
:target: https://odoo-community.org/page/development-status
|
||||
:alt: Beta
|
||||
.. |badge2| image:: https://img.shields.io/badge/license-AGPL--3-blue.png
|
||||
:target: http://www.gnu.org/licenses/agpl-3.0-standalone.html
|
||||
:alt: License: AGPL-3
|
||||
.. |badge3| image:: https://img.shields.io/badge/github-cetmix%2Fcetmix--tower-lightgray.png?logo=github
|
||||
:target: https://github.com/cetmix/cetmix-tower/tree/18.0/cetmix_tower_aws
|
||||
:alt: cetmix/cetmix-tower
|
||||
|
||||
|badge1| |badge2| |badge3|
|
||||
|
||||
**⚠️ DISCLAIMER: TECHNICAL MODULE**
|
||||
|
||||
This module integrates Boto3 library, the Amazon Web Services (AWS)
|
||||
Software Development Kit (SDK) for Python, into the Cetmix Tower.
|
||||
|
||||
**This is a technical module intended for system administrators or
|
||||
DevOps professionals.** It may involve server configuration,
|
||||
infrastructure management, or advanced setup outside the standard
|
||||
Odoo interface. Not intended for direct use by end users.
|
||||
|
||||
**Table of contents**
|
||||
|
||||
.. contents::
|
||||
:local:
|
||||
|
||||
Use Cases / Context
|
||||
===================
|
||||
|
||||
Although Amazon Web Services (AWS) allows API calls without using an
|
||||
SDK, we found that integrating the Amazon SDK into Cetmix Tower makes
|
||||
provisioning, configuring, and maintaining AWS instances more convenient
|
||||
for the end user. However, not all Cetmix Tower users require this
|
||||
functionality, so to avoid overloading the system, we have included it
|
||||
in a separate module.
|
||||
|
||||
Configuration
|
||||
=============
|
||||
|
||||
**Prerequisites**
|
||||
|
||||
The module has ``boto3`` defined in its external dependencies, which
|
||||
means, you should install the Python ``boto3`` package manually if you
|
||||
don't have automatic package installation configured in your Odoo
|
||||
environment. Run ``pip install boto3`` to install it.
|
||||
|
||||
**Setting up AWS Access**
|
||||
|
||||
1. **Create AWS Access Keys**
|
||||
|
||||
To use the AWS integration with Cetmix Tower, you need to create AWS
|
||||
access keys:
|
||||
|
||||
- Follow the `official AWS
|
||||
documentation <https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html>`__
|
||||
(https://docs.aws.amazon.com/IAM/latest/UserGuide/security-creds.html)
|
||||
for creating IAM access keys
|
||||
- It's recommended to create a dedicated IAM user with appropriate
|
||||
permissions for Cetmix Tower
|
||||
- Store your access key ID and secret access key securely - you'll
|
||||
need them in the next step
|
||||
|
||||
2. **Configure AWS Secrets in Cetmix Tower**
|
||||
|
||||
Create two secrets in Cetmix Tower to store your AWS credentials:
|
||||
|
||||
- Navigate to ``Cetmix Tower > Settings > Keys and Secrets``
|
||||
- Create a new Secret with:
|
||||
|
||||
- Name: ``AWS Access Key``
|
||||
- Reference: ``aws_access_key``
|
||||
- Key Type: ``Secret``
|
||||
|
||||
- Enter your AWS access key ID in the Secret Value tab
|
||||
- Similarly, create another Secret with:
|
||||
|
||||
- Name: ``AWS Secret Access Key``
|
||||
- Reference: ``aws_secret_access_key``
|
||||
- Key Type: ``Secret``
|
||||
|
||||
- Enter your AWS secret access key in the Secret Value tab
|
||||
|
||||
..
|
||||
|
||||
Note: These secrets will be accessible as
|
||||
``#!cxtower.secret.aws_access_key!#`` and
|
||||
``#!cxtower.secret.aws_secret_access_key!#`` in your commands.
|
||||
|
||||
3. **Configure AWS Region**
|
||||
|
||||
Create a variable to define your AWS region:
|
||||
|
||||
- Navigate to ``Cetmix Tower > Settings > Variables``
|
||||
- Create a new Variable with:
|
||||
|
||||
- Name: ``AWS Region Name``
|
||||
- Reference: ``aws_region_name``
|
||||
- Type: ``String``
|
||||
|
||||
- Set your AWS region (e.g., ``us-east-1``, ``eu-west-1``) as the
|
||||
value
|
||||
|
||||
Usage
|
||||
=====
|
||||
|
||||
Please check the `official Boto3
|
||||
Documentation <https://boto3.amazonaws.com/v1/documentation/api/latest/index.html>`__
|
||||
(https://boto3.amazonaws.com/v1/documentation/api/latest/index.html) for
|
||||
the detailed information about the services and methods provided by the
|
||||
Boto3 library.
|
||||
|
||||
**Disclaimer**: The following example demonstrates one of many
|
||||
possible commands you can create and run with this module. The boto3
|
||||
library provides access to the full range of AWS services and methods
|
||||
- this is just a starting point to help you get familiar with the
|
||||
integration.
|
||||
|
||||
Example of Cetmix Tower Python Command to List EC2 Instances
|
||||
------------------------------------------------------------
|
||||
|
||||
Navigate to Command Creation
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- Go to ``Cetmix Tower > Commands > Commands``
|
||||
- Click the ``Create`` button
|
||||
|
||||
Configure Command Settings
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- Set a descriptive ``Name`` (e.g., "List AWS EC2 Instances")
|
||||
- Leave ``Reference`` blank to generate automatically (or set a custom
|
||||
reference)
|
||||
- Select ``Action``: "Execute Python code"
|
||||
- Set ``Access Level``: Choose appropriate level (e.g., "Manager")
|
||||
- Optional: Set ``Default Path`` if needed
|
||||
- Optional: Add ``Tags`` (e.g., "aws", "ec2") for better organization
|
||||
|
||||
Add Required Variables
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- In the ``Variables`` tab, add the previously configured variable:
|
||||
|
||||
- ``aws_region_name``
|
||||
|
||||
Add Required Secrets
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- In the ``Secrets`` field, add the previously configured secrets:
|
||||
|
||||
- ``aws_access_key``
|
||||
- ``aws_secret_access_key``
|
||||
|
||||
Write Python Code
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
- Go to the ``Code`` tab
|
||||
|
||||
- Enter the following Python code:
|
||||
|
||||
.. code:: python
|
||||
|
||||
# List EC2 instances using boto3
|
||||
result = {"exit_code": 0, "message": None}
|
||||
|
||||
session = boto3.Session(
|
||||
aws_access_key_id=#!cxtower.secret.aws_access_key!#,
|
||||
aws_secret_access_key=#!cxtower.secret.aws_secret_access_key!#,
|
||||
region_name={{ aws_region_name }}
|
||||
)
|
||||
ec2 = session.client('ec2')
|
||||
instances = ec2.describe_instances()
|
||||
|
||||
instance_details = []
|
||||
for reservation in instances['Reservations']:
|
||||
for instance in reservation['Instances']:
|
||||
instance_detail = "Instance ID: " + instance['InstanceId']
|
||||
instance_detail += ", Type: " + instance.get('InstanceType', 'Unknown')
|
||||
instance_detail += ", State: " + instance.get('State', {}).get('Name', 'Unknown')
|
||||
instance_details.append(instance_detail)
|
||||
|
||||
if instance_details:
|
||||
result["message"] = "Found " + str(len(instance_details)) + " EC2 instances:\n" + "\n".join(instance_details)
|
||||
else:
|
||||
result["message"] = "No EC2 instances found"
|
||||
|
||||
Save the Command
|
||||
~~~~~~~~~~~~~~~~
|
||||
|
||||
- Click the ``Save`` button to create the command
|
||||
|
||||
Running the AWS EC2 Command
|
||||
---------------------------
|
||||
|
||||
Navigate to Server
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- Go to ``Cetmix Tower > Servers > Servers``
|
||||
- Open the server where you want to run the command
|
||||
|
||||
Execute Command from Server
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- Click the ``Command`` button at the top of the server form
|
||||
- In the popup dialog:
|
||||
|
||||
- Select your AWS EC2 command from the dropdown
|
||||
- Verify the variable values (if any need adjustment)
|
||||
- Click ``Run`` to execute
|
||||
|
||||
View Command Results
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
- After execution, the command log will display showing:
|
||||
|
||||
- The command executed
|
||||
- Execution status
|
||||
- Output message containing EC2 instance details if successful
|
||||
|
||||
Example Output
|
||||
--------------
|
||||
|
||||
For a successful execution with EC2 instances:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
Found 3 EC2 instances:
|
||||
Instance ID: i-0abc123def456789, Type: t2.micro, State: running
|
||||
Instance ID: i-0def456abc789123, Type: t3.medium, State: stopped
|
||||
Instance ID: i-0789abc123def456, Type: m5.large, State: running
|
||||
|
||||
For a successful execution with no EC2 instances:
|
||||
|
||||
.. code:: bash
|
||||
|
||||
No EC2 instances found
|
||||
|
||||
Creating Additional AWS Commands
|
||||
--------------------------------
|
||||
|
||||
The cetmix_tower_aws module provides access to the boto3 Python library
|
||||
for AWS service integration. Here are some common services you can use:
|
||||
|
||||
.. code:: python
|
||||
|
||||
# Standard client initialization pattern
|
||||
client = boto3.client(
|
||||
'service_name', # Replace with: ec2, s3, rds, cloudwatch, etc.
|
||||
region_name={{ aws_region_name }},
|
||||
aws_access_key_id=#!cxtower.secret.aws_access_key!#,
|
||||
aws_secret_access_key=#!cxtower.secret.aws_secret_access_key!#
|
||||
)
|
||||
|
||||
# Or use resource interface for object-oriented access
|
||||
resource = boto3.resource(
|
||||
'service_name', # Replace with: ec2, s3, etc.
|
||||
region_name={{ aws_region_name }},
|
||||
aws_access_key_id=#!cxtower.secret.aws_access_key!#,
|
||||
aws_secret_access_key=#!cxtower.secret.aws_secret_access_key!#
|
||||
)
|
||||
|
||||
Popular AWS services include: EC2 (compute), S3 (storage), RDS
|
||||
(databases), and CloudWatch (monitoring).
|
||||
|
||||
For more details, see the `AWS Boto3
|
||||
Documentation <https://boto3.amazonaws.com/v1/documentation/api/latest/index.html>`__.
|
||||
|
||||
Changelog
|
||||
=========
|
||||
|
||||
|
||||
|
||||
Bug Tracker
|
||||
===========
|
||||
|
||||
Bugs are tracked on `GitHub Issues <https://github.com/cetmix/cetmix-tower/issues>`_.
|
||||
In case of trouble, please check there if your issue has already been reported.
|
||||
If you spotted it first, help us to smash it by providing a detailed and welcomed
|
||||
`feedback <https://github.com/cetmix/cetmix-tower/issues/new?body=module:%20cetmix_tower_aws%0Aversion:%2018.0%0A%0A**Steps%20to%20reproduce**%0A-%20...%0A%0A**Current%20behavior**%0A%0A**Expected%20behavior**>`_.
|
||||
|
||||
Do not contact contributors directly about support or help with technical issues.
|
||||
|
||||
Credits
|
||||
=======
|
||||
|
||||
Authors
|
||||
-------
|
||||
|
||||
* Cetmix
|
||||
|
||||
Maintainers
|
||||
-----------
|
||||
|
||||
This module is part of the `cetmix/cetmix-tower <https://github.com/cetmix/cetmix-tower/tree/18.0/cetmix_tower_aws>`_ project on GitHub.
|
||||
|
||||
You are welcome to contribute.
|
||||
Reference in New Issue
Block a user