Merge "update of Installation Guide"

This commit is contained in:
Zuul 2017-10-20 09:48:41 +00:00 committed by Gerrit Code Review
commit 062966e4a3
16 changed files with 234 additions and 128 deletions

View File

@ -46,7 +46,7 @@ source_suffix = '.rst'
master_doc = 'index'
# General information about the project.
project = 'ec2-api'
project = 'EC2API Service'
copyright = '2015, OpenStack Foundation'
# If true, '()' will be appended to :func: etc. cross-reference text.

View File

@ -1,3 +1,5 @@
.. _configuring:
===================
Configuring EC2-API
===================
@ -11,7 +13,7 @@ To configure your EC2API installation, you must define configuration options in
A list of config options based on different topics can be found below:
.. toctree::
:maxdepth: 2
:maxdepth: 1
api.rst
metadata.rst

View File

@ -3,14 +3,26 @@ OpenStack EC2 API
Support of EC2 API for OpenStack.
This project provides a standalone EC2 API service which pursues two goals:
1. Implement VPC API which is now absent in nova's EC2 API
2. Create a standalone service for EC2 API support which accommodates
not only the VPC API but the rest of the EC2 API currently present in nova as
well.
not only the VPC API but the rest of the EC2 API currently present in nova as
well.
It doesn't replace existing nova EC2 API service in deployment, it gets
installed to a different port (8788 by default).
The ec2-api service consists of the following components:
``ec2-api`` service
Accepts and responds to end user EC2 and VPC API calls.
``ec2-api-metadata`` service
Provides the OpenStack Metadata API to servers. The metadata is used to
configure the running servers.
Installing EC2API
=================

View File

@ -0,0 +1,60 @@
.. _configuration:
To configure OpenStack for EC2 API service add to ``/etc/ec2api/ec2api.conf``:
.. code-block:: ini
[DEFAULT]
external_network = public
ec2_port = 8788
ec2api_listen_port = 8788
keystone_ec2_tokens_url = http://192.168.56.101/identity/v3/ec2tokens
api_paste_config = /etc/ec2api/api-paste.ini
disable_ec2_classic = True
.. [*] - ``external_network`` option specifies the name of the external network,
which is used to Internet and to allocate Elastic IPs. It must be
specified to get access into VMs from outside of the cloud.
- ``disable_ec2_classic`` option is not mandatory, but we strongly
recommend it to be specified. It turns off EC2 Classic mode and forces
objects to be created inside VPCs.
With ``disable_ec2_classic`` = True, any user of the cloud must have
the only network (created with neutron directly and attached to a router
to provide outside access for that VMS), which is used for launch
ec2-classic instances.
Keep in mind that an operator is not able to change
``disable_ec2_classic`` setting seamlessly.
In the *[keystone_authtoken]* section, configure Identity service access.
.. code-block:: ini
[keystone_authtoken]
project_domain_name = Default
project_name = service
user_domain_name = Default
password = password
username = ec2api
auth_type = password
Also you need to configure database connection:
.. code-block:: ini
[database]
connection = mysql+pymysql://root:password@127.0.0.1/ec2api?charset=utf8
and cache if you want to use it.
.. code-block:: ini
[cache]
backend = oslo_cache.dict
enabled = True
You can look for other configuration options in the `Configuration Reference`_
.. _`Configuration Reference`: ../configuration/api.html

View File

@ -1,18 +1,8 @@
.. _credentials-creation:
Creating the service credentials
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The service credentials are created automatically by the install.sh. To create
them manually, complete these steps:
#. Source the ``admin`` credentials to gain access to
admin-only CLI commands:
.. code-block:: console
$ . admin-openrc
#. To create the service credentials, complete these steps:
* Create the ``ec2api`` user:

View File

@ -1,12 +1,5 @@
.. _database-creation:
Creating the database
~~~~~~~~~~~~~~~~~~~~~
The database is created automatically by the install.sh.
To create the database manually, complete these steps:
* Use the database access client to connect to the database
server as the ``root`` user:
@ -22,7 +15,7 @@ To create the database manually, complete these steps:
* Grant proper access to the ``ec2api`` database:
.. code-block:: console
.. code-block:: ini
GRANT ALL PRIVILEGES ON ec2api.* TO 'ec2api'@'localhost' \
IDENTIFIED BY 'EC2-API_DBPASS';

View File

@ -9,5 +9,5 @@ Create the ec2api service API endpoints:
$ openstack endpoint create --region RegionOne ec2api \
internal http://controller:XXXX/
- where 'controller' is address of controller,
- and 'XXXX' is port your ec2api is installed on (8788 by default)
- where 'controller' is address your ec2api is installed on
- and 'XXXX' is port (8788 by default)

View File

@ -1,15 +0,0 @@
=========================
EC2-API service overview
=========================
The ec2-api service provides Amazon EC2 API support.
The ec2-api service consists of the following components:
``ec2-api`` service
Accepts and responds to end user EC2 and VPC API calls.
``ec2-api-metadata`` service
Provides the OpenStack Metadata API to servers. The metadata is used to
configure the running servers.

View File

@ -2,11 +2,24 @@
Installing EC2-API
=====================
.. toctree::
:maxdepth: 2
This section describes how to install and configure the ec2-api service on the
controller node for Ubuntu (LTS).
It assumes that you already have a working OpenStack environment with
at least the following components installed: Compute, Networking, Block Storage,
Identity, Image.
.. toctree::
:maxdepth: 1
install-sh.rst
install-manual.rst
install-devstack.rst
.. toctree::
:maxdepth: 1
get-started.rst
install.rst
verify.rst
next-steps.rst

View File

@ -0,0 +1,15 @@
.. _install-devstack:
Installation on DevStack
~~~~~~~~~~~~~~~~~~~~~~~~~
In order to install ec2-api with devstack the following should be added to the local.conf or localrc the following line:
.. code-block:: ini
enable_plugin ec2-api https://git.openstack.org/openstack/ec2-api
Configuring OpenStack for EC2 API metadata service
---------------------------------------------------
.. include:: metadata-configuration.rst

View File

@ -0,0 +1,47 @@
.. _install-manual:
Manual Installation
~~~~~~~~~~~~~~~~~~~
Install and configure components
--------------------------------
1. Install the packages in any way you prefer
(**github+setup.py** / **pip** / **packages**)
2. Create the service credentials
.. include:: credentials-creation.rst
3. Create database
.. include:: database-creation.rst
There is a script creating 'ec2api' database that is accessible
only on localhost by user 'ec2api' with password 'ec2api'.
https://github.com/openstack/ec2-api/blob/master/tools/db/ec2api-db-setup
4. Create endpoints:
.. include:: endpoints-creation.rst
5. Create configuration files ``/etc/ec2api/api-paste.ini``
(can be copied from
https://github.com/openstack/ec2-api/blob/master/etc/ec2api/api-paste.ini)
and ``/etc/ec2api/ec2api.conf``
.. include:: configuration.rst
6. Configure metadata:
.. include:: metadata-configuration.rst
7. Start the services as binaries
.. code-block:: console
$ /usr/local/bin/ec2-api
$ /usr/local/bin/ec2-api-metadata
or set up as Linux services.

View File

@ -0,0 +1,38 @@
.. _install-sh:
Installation by install.sh
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Install and configure components
--------------------------------
Install the packages:
.. code-block:: console
# apt-get update
# git clone https://github.com/openstack/ec2-api.git
# cd ec2-api
Run install.sh
The EC2 API service gets installed on port 8788 by default. It can be changed
before the installation in ``/etc/ec2api/ec2api.conf`` configuration file.
:ref:`configuring`.
The services afterwards can be started as binaries:
.. code-block:: console
$ /usr/local/bin/ec2-api
$ /usr/local/bin/ec2-api-metadata
or set up as Linux services.
.. include:: endpoints-creation.rst
Configuring OpenStack for EC2 API metadata service
---------------------------------------------------
.. include:: metadata-configuration.rst

View File

@ -1,64 +1,19 @@
.. _install-ubuntu:
Installation on existing OpenStack deployment
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
This section describes how to install and configure the ec2-api
service for Ubuntu (LTS).
Install and configure
~~~~~~~~~~~~~~~~~~~~~
Install and configure components
--------------------------------
This section describes how to install and configure the ec2-api service on the
controller node for Ubuntu (LTS).
Install the packages:
It assumes that you already have a working OpenStack environment with
at least the following components installed: Compute, Networking, Block Storage,
Identity, Image.
.. code-block:: console
.. toctree::
:maxdepth: 1
# apt-get update
# git clone https://github.com/openstack/ec2-api.git
# cd ec2-api
Run install.sh
The EC2 API service gets installed on port 8788 by default. It can be changed
before the installation in install.sh script.
The services afterwards can be started as binaries:
::
/usr/local/bin/ec2-api
/usr/local/bin/ec2-api-metadata
or set up as Linux services.
.. include:: endpoints-creation.rst
Configuring OpenStack for EC2 API metadata service
--------------------------------------------------
To configure OpenStack for EC2 API metadata service:
for Nova-network add:
.. code-block:: console
# [DEFAULT]
# metadata_port = 8789
# [neutron]
# service_metadata_proxy = True
to ``/etc/nova.conf``
then restart nova-metadata (can be run as part of nova-api service) and
nova-network services.
for Neutron add:
.. code-block:: console
# [DEFAULT]
# nova_metadata_port = 8789
to ``/etc/neutron/metadata_agent.ini``
then restart neutron-metadata service.
install-sh.rst
install-manual.rst
install-devstack.rst

View File

@ -1,24 +0,0 @@
.. _install:
Install and configure
~~~~~~~~~~~~~~~~~~~~~
This section describes how to install and configure the ec2-api service on the
controller node.
This section assumes that you already have a working OpenStack environment with
at least the following components installed: Compute, Networking, Block Storage,
Identity, Image.
.. toctree::
:maxdepth: 2
install-ubuntu.rst
Additional steps:
.. toctree::
:maxdepth: 2
database-creation.rst
credentials-creation.rst

View File

@ -0,0 +1,14 @@
EC2 metadata is built in between the nova-metadata and the neutron-metadata,
so we need to configure Neutron so that it sends requests to ec2-api-metadata,
not to the nova.
To configure OpenStack for EC2 API metadata service for Neutron add:
.. code-block:: ini
[DEFAULT]
nova_metadata_port = 8789
to ``/etc/neutron/metadata_agent.ini``
then restart neutron-metadata service.

View File

@ -14,7 +14,7 @@ Verify operation of the ec2-api service.
.. code-block:: console
$ . admin-openrc
$ . openrc admin admin
#. List service components to verify successful launch and registration
of each process:
@ -24,8 +24,14 @@ Verify operation of the ec2-api service.
$ openstack service list
#. Download aws cli from Amazon. Create configuration file for aws cli in your
home directory ``~/.aws/config``:
#. Install aws cli.
.. code-block:: console
# pip install awscli --upgrade --user
#. Create configuration file for aws cli in your home directory
``~/.aws/config`` or by "**aws configure**" command:
.. code-block:: console
@ -36,7 +42,7 @@ Verify operation of the ec2-api service.
Change the aws_access_key_id and aws_secret_acces_key above to the values
appropriate for your cloud (can be obtained by
**"openstack ec2 credentials list"** command).
"**openstack ec2 credentials list**" command).
#. Run aws cli commands using new EC2 API endpoint URL (can be obtained from
keystone with the new port 8788) like this: