Skip to content
Snippets Groups Projects
Commit bec6d96d authored by Yas Naoi's avatar Yas Naoi Committed by Yas Naoi
Browse files

Issue #3221405 by yas, kleiton_rodrigues, kumikoono, Webbeh, baldwinlouie: Update README.md

parent c9db2606
No related branches found
No related tags found
No related merge requests found
INTRODUCTION
Introduction
============
Cloud is a set of modules to realize Cloud management: Drupal-based Cloud
dashboard such as Amazon Management Console, RightScale, ElasticFox, etc.
The module aims to support not only public Cloud like Amazon EC2 but also
private Cloud like Kubernetes, VMware or OpenStack since the system is highly
modularized by Drupal architecture.
Cloud is a set of modules to enable Cloud orchestration: A Drupal-based
Cloud dashboard for _AWS_, _Kubernetes_, _OpenStack_, _VMware_ and _Terraform
Cloud_ as a one stop portal to manage multiple cloud service providers.
REQUIREMENTS
Requirements
============
- `PHP 7.4` or Higher (`128 MB` Memory or higher)
- `MySQL 5.7` or higher _OR_
- `MariaDB 10.3` or higher
- `Drupal 9.2.x` or higher (The latest version of `Drupal 9.2.x`)
- `Cloud 4.x`
- This branch includes support for `AWS`, `OpenStack`, `Kubernetes`,
`VMware` and `Terraform Cloud`
- Future support includes `GCP` and `MS Azure`.
- `AWS`
- Mandatory `IAM permissions` for creating a cloud service provider are:
- `"ec2:DescribeAddresses"`,
- `"ec2:DescribeAvailabilityZones"`,
- `"ec2:DescribeIamInstanceProfileAssociations"`,
- `"ec2:DescribeCarrierGateways"`,
- `"ec2:DescribeFlowLogs"`,
- `"ec2:DescribeImageAttribute",`
- `"ec2:DescribeImages"`,
- `"ec2:DescribeInstanceAttribute"`,
- `"ec2:DescribeInstances"`,
- `"ec2:DescribeInternetGateways"`,
- `"ec2:DescribeKeyPairs"`,
- `"ec2:DescribeLaunchTemplates"`,
- `"ec2:DescribeLaunchTemplateVersions"`,
- `"ec2:DescribeNetworkInterfaces"`,
- `"ec2:DescribeSecurityGroups"`,
- `"ec2:DescribeSnapshots"`,
- `"ec2:DescribeSubnets"`,
- `"ec2:DescribeTransitGateways"`,
- `"ec2:DescribeVolumes"`,
- `"ec2:DescribeVpcPeeringConnections"`,
- `"ec2:DescribeVpcs"`,
- `"iam:ListInstanceProfiles"`
- Optional `IAM permissions` for creating a cloud service provider are:
- `"cloudwatch:GetMetricData"`,
- `"ec2:AuthorizeSecurityGroupEgress"`,
- `"ec2:AuthorizeSecurityGroupIngress"`,
- `"ec2:CreateKeyPair"`,
- `"ec2:CreateLaunchTemplate"`,
- `"ec2:CreateNetworkInterface"`,
- `"ec2:CreateSecurityGroup"`,
- `"ec2:CreateSnapshot"`,
- `"ec2:CreateSubnet"`,
- `"ec2:CreateTags"`,
- `"ec2:CreateVpc"`,
- `"ec2:GetConsoleOutput"`,
- `"ec2:RevokeSecurityGroupEgress"`,
- `"ec2:RevokeSecurityGroupIngress"`
- PHP `8.0` or higher (`128 MB` memory or higher)
- MySQL `5.7` or higher _OR_ MariaDB `10.3` or higher
- Drupal `9.2` or higher
- Cloud `4.x`
- This branch includes support for _AWS_, _Kubernetes_, _OpenStack_,
_VMware_ and _Terraform Cloud_
- Future support includes _GCP_ and _MS Azure_
Limitations
===========
- The aws_cloud module does **not** support *Classic EC2 instances*
(`Non-VPC`).
- The `aws_cloud` module does **not** support *Classic EC2 instances*
(_Non-VPC_).
**Note:** Classic instances (`Non-VPC`) are available for AWS accounts
created before *2013-12-03*.
`aws_cloud` module is only tested for `EC2-VPC` instances.
**Note:** Classic instances (_Non-VPC_) are available for AWS accounts
created before *2013-12-03*.
`aws_cloud` module is only tested for _EC2-VPC_ instances.
See also:
- [Default VPC and Default Subnets](
......@@ -79,44 +34,130 @@ Limitations
https://forums.aws.amazon.com/thread.jspa?threadID=182773
)
INSTALLATION
=============
1. Download `aws-sdk` from:
https://docs.aws.amazon.com/aws-sdk-php/v3/download/aws.zip
and unzip it into the `vendor` directory.
2. Download `cloud` module.
3. Enable the `aws_cloud module`. This will also enable the required modules.
_OR_ (using `composer`)
Installation
============
- `composer require drupal/cloud`
- There are the following options to install `cloud` module as a [Cloud
Orchestrator](https://www.drupal.org/project/cloud_orchestrator) distribution:
1. Use PHP composer: `composer create-project
docomoinnovations/cloud_orchestrator cloud_orchestrator`
2. Launch Cloud [Cloud Orchestrator](
https://www.drupal.org/project/cloud_orchestrator
) `4.x` from [AWS Marketplace](
https://aws.amazon.com/marketplace/pp/B08PN2Z6X6?ref_=srh_res_product_title
)
3. Launch an Amazon EC2 instance of Cloud Orchestrator using
[AWS CloudFormation Template](
https://cloud-orchestrator.s3.amazonaws.com/cfn/cloud_orchestrator_single.yaml
)
4. [Download the module](
https://www.drupal.org/project/cloud
) directly to an existing Drupal installation
CONFIGURATION
Configuration
=============
IAM Policy (AWS)
----------------
- Before you create a new _AWS Cloud service provider_, you may want to
configure _IAM Policy_ as follows:
- Mandatory _IAM policy_ for creating an _AWS Cloud service provider_
are:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Mandatory",
"Effect": "Allow",
"Action": [
"ec2:DescribeAddresses",
"ec2:DescribeAvailabilityZones",
"ec2:DescribeIamInstanceProfileAssociations",
"ec2:DescribeCarrierGateways",
"ec2:DescribeFlowLogs",
"ec2:DescribeImageAttribute",
"ec2:DescribeImages",
"ec2:DescribeInstanceAttribute",
"ec2:DescribeInstances",
"ec2:DescribeInternetGateways",
"ec2:DescribeKeyPairs",
"ec2:DescribeLaunchTemplates",
"ec2:DescribeLaunchTemplateVersions",
"ec2:DescribeNetworkInterfaces",
"ec2:DescribeSecurityGroups",
"ec2:DescribeSnapshots",
"ec2:DescribeSubnets",
"ec2:DescribeTransitGateways",
"ec2:DescribeVolumes",
"ec2:DescribeVpcPeeringConnections",
"ec2:DescribeVpcs",
"iam:ListInstanceProfiles"
],
"Resource": "*"
}
]
}
```
- Optional _IAM policy_ for creating an _AWS Cloud service provider_ are:
```
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "Optional",
"Effect": "Allow",
"Action": [
"cloudwatch:GetMetricData",
"ec2:AuthorizeSecurityGroupEgress",
"ec2:AuthorizeSecurityGroupIngress",
"ec2:CreateKeyPair",
"ec2:CreateLaunchTemplate",
"ec2:CreateNetworkInterface",
"ec2:CreateSecurityGroup",
"ec2:CreateSnapshot",
"ec2:CreateSubnet",
"ec2:CreateTags",
"ec2:CreateVpc",
"ec2:GetConsoleOutput",
"ec2:RevokeSecurityGroupEgress",
"ec2:RevokeSecurityGroupIngress"
],
"Resource": "*"
}
]
}
```
- The resource field should limit to the AWS account number and target
resource e.g. `"Resource": "arn:aws:ec2:*:049876562615:key-pair/*"`.
- See also: [Example policies for working in the Amazon EC2 console](
https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/iam-policies-ec2-console.html
)
Basic Setup (AWS)
-----------------
1. Create a new `cloud service provider` based on your needs.
Go to `Structure` > `Cloud service providers` and
`+ Add cloud service provider`
1. Add a new _AWS cloud service provider_ based on your needs.
Go to `Structure` > `Cloud service providers` and click
`+ Add cloud service provider` for _AWS Cloud_
2. Enter all required configuration parameters. The system will automatically
setup all regions from your AWS account. There are three options for
specifying AWS credentials:
a. Instance credentials - If cloud module is running on an EC2 instance and
the EC2 instance has an IAM role attached, you have the option to check "Use
Instance Credentials". Doing so is secure and does not require `Access Key
ID` and `Secret Access Key` to be entered into Drupal.
Please refer to this AWS tutorial about IAM role and EC2 Instance:
1. Instance credentials - If cloud module is running on an EC2 instance and
the EC2 instance has an IAM role attached, you have the option to check
`Use Instance Credentials`. Doing so is secure and does not require
`Access Key ID` and `Secret Access Key` to be entered into Drupal.
Please refer to this AWS tutorial about IAM role and EC2 Instance:
https://aws.amazon.com/blogs/security/easily-replace-or-attach-an-iam-role-to-an-existing-ec2-instance-by-using-the-ec2-console/
https://aws.amazon.com/blogs/security/easily-replace-or-attach-an-iam-role-to-an-existing-ec2-instance-by-using-the-ec2-console/
b. Simple access - Specify `Access Key ID` and `Secret Access Key` to access
2. Simple access - Specify `Access Key ID` and `Secret Access Key` to access
a particular account's EC2 instances.
c. Assume role - Specify `Access Key ID`, `Secret Access Key` and the
`Assume Role` section. With this combination, the cloud module can
3. Assume role - Specify `Access Key ID`, `Secret Access Key` and the
`Assume Role` section. With this combination, the `cloud` module can
assume the role of another AWS account and access their EC2 instances.
To learn more about setting up assume role setup, please read this AWS
tutorial:
......@@ -139,56 +180,70 @@ Basic Setup (AWS)
pair. You will be uploading your public key.
- Use `+ Add AWS Cloud Key Pair` to have AWS generate a new private key.
You will be prompted to download the key after it is created.
7. Setup `Security groups`, `Network Interfaces` as needed from AWS Management
Console.
7. Setup `Security groups`, `Network Interfaces` as needed.
Launching Instance
------------------
1. Create a launch template under
`Design` > `Launch template` > `[Cloud service provider]`
2. Once template is created, click the `Launch` tab to launch it.
2. After creating a template, change the workflow status to `Approved`.
3. Click the `Launch` tab to launch it.
Permissions
===========
-----------
- Configure permissions per your requirements.
- [The detail about permissions is here.](
https://www.drupal.org/docs/8/modules/cloud/configuration)
https://www.drupal.org/docs/8/modules/cloud/configuration
)
Module Structure
================
`cloud` is the heart of modules of the `Cloud` and `Cloud service provider`
packages.
Directory Structure
===================
```
cloud (Cloud is a core module for Cloud package)
└── modules
└── cloud_budget
└── cloud_service_providers
└── aws_cloud
└── k8s
└── docker
└── openstack
└── terraform
└── vmware
└── gapps
└── tools
└── k8s_to_s3
└── s3_to_k8s
cloud
`-- modules
|-- cloud_budget
|-- cloud_cluster_worker
|-- cloud_service_providers
| |-- aws_cloud
| |-- cloud_cluster
| |-- docker
| |-- k8s
| |-- openstack
| |-- terraform
| `-- vmware
|-- gapps
`-- tools
|-- k8s_to_s3
`-- s3_to_k8s
```
Known Issues
============
When adding a Metrics Server enabled Kubernetes cluster, the metrics
importing operation can potentially take a long time to complete.
During this process, there might be database corruption if the aws_cloud
module is enabled.
As a workaround, enable aws_cloud when the server is idle and not processing
a `Add Kubernetes Cloud Service Provider` operation.
Active Maintainers
==================
- When adding a Metrics Server enabled Kubernetes cluster, the metrics
importing operation can potentially take a long time to complete.
During this process, there might be database corruption if the `aws_cloud`
module is enabled.
- As a workaround, enable `aws_cloud` when the server is idle and not processing
an `Add cloud Service Provider` for _Kuberentes_ operation.
- `504 Gateway timeout` occurs while adding an _AWS Cloud service provider_
with all AWS regions.
- `504 Gateway timeout` occurs while adding a _K8s cloud service provider_ on
GCP.
Maintainers
===========
- `yas` (https://drupal.org/u/yas)
- `baldwinlouie` (https://www.drupal.org/u/baldwinlouie)
- `jigish.addweb` (https://www.drupal.org/u/jigishaddweb)
- `Masami` (https://www.drupal.org/u/Masami)
- `MasatoTakada` (https://www.drupal.org/u/masatotakada)
- `Hiroki Moriya` (https://www.drupal.org/u/hiroki-moriya)
- `Kumiko Ono (kumikoono)` (https://www.drupal.org/u/kumikoono)
- `Lidia Matei (XLD)` (https://www.drupal.org/u/xld)
- `Masami Suzuki (Masami)` (https://www.drupal.org/u/Masami)
- `Ryo Yamashita` (https://www.drupal.org/u/ryo-yamashita)
- `Takumaru Sekine (sekinet)` (https://www.drupal.org/u/sekinet)
- `Xiaohua Guan` (https://www.drupal.org/u/xiaohua-guan)
0% Loading or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment