summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorZuul <zuul@review.openstack.org>2017-10-20 09:48:41 +0000
committerGerrit Code Review <review@openstack.org>2017-10-20 09:48:41 +0000
commit062966e4a38a97c0e0c25128c40f39402706b2be (patch)
treefb90eca7bef656de00d3be315cf7215f5c3893eb
parentc5f4ce8edafaadcac7e79040e61c4e2443396444 (diff)
parent41309f5922dfa5edaa3c675200fac4d975118a20 (diff)
Merge "update of Installation Guide"
-rw-r--r--doc/source/conf.py2
-rw-r--r--doc/source/configuration/index.rst4
-rw-r--r--doc/source/index.rst16
-rw-r--r--doc/source/install/configuration.rst60
-rw-r--r--doc/source/install/credentials-creation.rst10
-rw-r--r--doc/source/install/database-creation.rst9
-rw-r--r--doc/source/install/endpoints-creation.rst4
-rw-r--r--doc/source/install/get-started.rst15
-rw-r--r--doc/source/install/index.rst19
-rw-r--r--doc/source/install/install-devstack.rst15
-rw-r--r--doc/source/install/install-manual.rst47
-rw-r--r--doc/source/install/install-sh.rst38
-rw-r--r--doc/source/install/install-ubuntu.rst69
-rw-r--r--doc/source/install/install.rst24
-rw-r--r--doc/source/install/metadata-configuration.rst14
-rw-r--r--doc/source/install/verify.rst14
16 files changed, 233 insertions, 127 deletions
diff --git a/doc/source/conf.py b/doc/source/conf.py
index f933c26..403f1d1 100644
--- a/doc/source/conf.py
+++ b/doc/source/conf.py
@@ -46,7 +46,7 @@ source_suffix = '.rst'
46master_doc = 'index' 46master_doc = 'index'
47 47
48# General information about the project. 48# General information about the project.
49project = 'ec2-api' 49project = 'EC2API Service'
50copyright = '2015, OpenStack Foundation' 50copyright = '2015, OpenStack Foundation'
51 51
52# If true, '()' will be appended to :func: etc. cross-reference text. 52# If true, '()' will be appended to :func: etc. cross-reference text.
diff --git a/doc/source/configuration/index.rst b/doc/source/configuration/index.rst
index 1054883..db48149 100644
--- a/doc/source/configuration/index.rst
+++ b/doc/source/configuration/index.rst
@@ -1,3 +1,5 @@
1.. _configuring:
2
1=================== 3===================
2Configuring EC2-API 4Configuring EC2-API
3=================== 5===================
@@ -11,7 +13,7 @@ To configure your EC2API installation, you must define configuration options in
11A list of config options based on different topics can be found below: 13A list of config options based on different topics can be found below:
12 14
13.. toctree:: 15.. toctree::
14 :maxdepth: 2 16 :maxdepth: 1
15 17
16 api.rst 18 api.rst
17 metadata.rst 19 metadata.rst
diff --git a/doc/source/index.rst b/doc/source/index.rst
index 27345ad..17135c0 100644
--- a/doc/source/index.rst
+++ b/doc/source/index.rst
@@ -3,14 +3,26 @@ OpenStack EC2 API
3 3
4Support of EC2 API for OpenStack. 4Support of EC2 API for OpenStack.
5This project provides a standalone EC2 API service which pursues two goals: 5This project provides a standalone EC2 API service which pursues two goals:
6
61. Implement VPC API which is now absent in nova's EC2 API 71. Implement VPC API which is now absent in nova's EC2 API
8
72. Create a standalone service for EC2 API support which accommodates 92. Create a standalone service for EC2 API support which accommodates
8not only the VPC API but the rest of the EC2 API currently present in nova as 10 not only the VPC API but the rest of the EC2 API currently present in nova as
9well. 11 well.
10 12
11It doesn't replace existing nova EC2 API service in deployment, it gets 13It doesn't replace existing nova EC2 API service in deployment, it gets
12installed to a different port (8788 by default). 14installed to a different port (8788 by default).
13 15
16The ec2-api service consists of the following components:
17
18``ec2-api`` service
19 Accepts and responds to end user EC2 and VPC API calls.
20
21``ec2-api-metadata`` service
22 Provides the OpenStack Metadata API to servers. The metadata is used to
23 configure the running servers.
24
25
14Installing EC2API 26Installing EC2API
15================= 27=================
16 28
diff --git a/doc/source/install/configuration.rst b/doc/source/install/configuration.rst
new file mode 100644
index 0000000..2ae95d2
--- /dev/null
+++ b/doc/source/install/configuration.rst
@@ -0,0 +1,60 @@
1.. _configuration:
2
3To configure OpenStack for EC2 API service add to ``/etc/ec2api/ec2api.conf``:
4
5.. code-block:: ini
6
7 [DEFAULT]
8 external_network = public
9 ec2_port = 8788
10 ec2api_listen_port = 8788
11 keystone_ec2_tokens_url = http://192.168.56.101/identity/v3/ec2tokens
12 api_paste_config = /etc/ec2api/api-paste.ini
13 disable_ec2_classic = True
14
15.. [*] - ``external_network`` option specifies the name of the external network,
16 which is used to Internet and to allocate Elastic IPs. It must be
17 specified to get access into VMs from outside of the cloud.
18
19 - ``disable_ec2_classic`` option is not mandatory, but we strongly
20 recommend it to be specified. It turns off EC2 Classic mode and forces
21 objects to be created inside VPCs.
22
23 With ``disable_ec2_classic`` = True, any user of the cloud must have
24 the only network (created with neutron directly and attached to a router
25 to provide outside access for that VMS), which is used for launch
26 ec2-classic instances.
27
28 Keep in mind that an operator is not able to change
29 ``disable_ec2_classic`` setting seamlessly.
30
31In the *[keystone_authtoken]* section, configure Identity service access.
32
33.. code-block:: ini
34
35 [keystone_authtoken]
36 project_domain_name = Default
37 project_name = service
38 user_domain_name = Default
39 password = password
40 username = ec2api
41 auth_type = password
42
43Also you need to configure database connection:
44
45.. code-block:: ini
46
47 [database]
48 connection = mysql+pymysql://root:password@127.0.0.1/ec2api?charset=utf8
49
50and cache if you want to use it.
51
52.. code-block:: ini
53
54 [cache]
55 backend = oslo_cache.dict
56 enabled = True
57
58You can look for other configuration options in the `Configuration Reference`_
59
60.. _`Configuration Reference`: ../configuration/api.html \ No newline at end of file
diff --git a/doc/source/install/credentials-creation.rst b/doc/source/install/credentials-creation.rst
index 59001de..9cf23e2 100644
--- a/doc/source/install/credentials-creation.rst
+++ b/doc/source/install/credentials-creation.rst
@@ -1,18 +1,8 @@
1.. _credentials-creation: 1.. _credentials-creation:
2 2
3Creating the service credentials
4~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5
6The service credentials are created automatically by the install.sh. To create
7them manually, complete these steps:
8
9#. Source the ``admin`` credentials to gain access to 3#. Source the ``admin`` credentials to gain access to
10 admin-only CLI commands: 4 admin-only CLI commands:
11 5
12 .. code-block:: console
13
14 $ . admin-openrc
15
16#. To create the service credentials, complete these steps: 6#. To create the service credentials, complete these steps:
17 7
18 * Create the ``ec2api`` user: 8 * Create the ``ec2api`` user:
diff --git a/doc/source/install/database-creation.rst b/doc/source/install/database-creation.rst
index 6911c48..98cb6bf 100644
--- a/doc/source/install/database-creation.rst
+++ b/doc/source/install/database-creation.rst
@@ -1,12 +1,5 @@
1.. _database-creation: 1.. _database-creation:
2 2
3Creating the database
4~~~~~~~~~~~~~~~~~~~~~
5
6The database is created automatically by the install.sh.
7
8To create the database manually, complete these steps:
9
10* Use the database access client to connect to the database 3* Use the database access client to connect to the database
11 server as the ``root`` user: 4 server as the ``root`` user:
12 5
@@ -22,7 +15,7 @@ To create the database manually, complete these steps:
22 15
23* Grant proper access to the ``ec2api`` database: 16* Grant proper access to the ``ec2api`` database:
24 17
25 .. code-block:: console 18 .. code-block:: ini
26 19
27 GRANT ALL PRIVILEGES ON ec2api.* TO 'ec2api'@'localhost' \ 20 GRANT ALL PRIVILEGES ON ec2api.* TO 'ec2api'@'localhost' \
28 IDENTIFIED BY 'EC2-API_DBPASS'; 21 IDENTIFIED BY 'EC2-API_DBPASS';
diff --git a/doc/source/install/endpoints-creation.rst b/doc/source/install/endpoints-creation.rst
index 3e2837d..53e605b 100644
--- a/doc/source/install/endpoints-creation.rst
+++ b/doc/source/install/endpoints-creation.rst
@@ -9,5 +9,5 @@ Create the ec2api service API endpoints:
9 $ openstack endpoint create --region RegionOne ec2api \ 9 $ openstack endpoint create --region RegionOne ec2api \
10 internal http://controller:XXXX/ 10 internal http://controller:XXXX/
11 11
12- where 'controller' is address of controller, 12- where 'controller' is address your ec2api is installed on
13- and 'XXXX' is port your ec2api is installed on (8788 by default) 13- and 'XXXX' is port (8788 by default)
diff --git a/doc/source/install/get-started.rst b/doc/source/install/get-started.rst
deleted file mode 100644
index e79caec..0000000
--- a/doc/source/install/get-started.rst
+++ /dev/null
@@ -1,15 +0,0 @@
1=========================
2EC2-API service overview
3=========================
4
5The ec2-api service provides Amazon EC2 API support.
6
7The ec2-api service consists of the following components:
8
9``ec2-api`` service
10 Accepts and responds to end user EC2 and VPC API calls.
11
12``ec2-api-metadata`` service
13 Provides the OpenStack Metadata API to servers. The metadata is used to
14 configure the running servers.
15
diff --git a/doc/source/install/index.rst b/doc/source/install/index.rst
index fc54c83..3118e5a 100644
--- a/doc/source/install/index.rst
+++ b/doc/source/install/index.rst
@@ -2,11 +2,24 @@
2Installing EC2-API 2Installing EC2-API
3===================== 3=====================
4 4
5This section describes how to install and configure the ec2-api service on the
6controller node for Ubuntu (LTS).
7
8It assumes that you already have a working OpenStack environment with
9at least the following components installed: Compute, Networking, Block Storage,
10Identity, Image.
11
12.. toctree::
13 :maxdepth: 1
14
15 install-sh.rst
16 install-manual.rst
17 install-devstack.rst
18
19
5.. toctree:: 20.. toctree::
6 :maxdepth: 2 21 :maxdepth: 1
7 22
8 get-started.rst
9 install.rst
10 verify.rst 23 verify.rst
11 next-steps.rst 24 next-steps.rst
12 25
diff --git a/doc/source/install/install-devstack.rst b/doc/source/install/install-devstack.rst
new file mode 100644
index 0000000..de422fa
--- /dev/null
+++ b/doc/source/install/install-devstack.rst
@@ -0,0 +1,15 @@
1.. _install-devstack:
2
3Installation on DevStack
4~~~~~~~~~~~~~~~~~~~~~~~~~
5
6In order to install ec2-api with devstack the following should be added to the local.conf or localrc the following line:
7
8.. code-block:: ini
9
10 enable_plugin ec2-api https://git.openstack.org/openstack/ec2-api
11
12Configuring OpenStack for EC2 API metadata service
13---------------------------------------------------
14
15.. include:: metadata-configuration.rst
diff --git a/doc/source/install/install-manual.rst b/doc/source/install/install-manual.rst
new file mode 100644
index 0000000..810ed4d
--- /dev/null
+++ b/doc/source/install/install-manual.rst
@@ -0,0 +1,47 @@
1.. _install-manual:
2
3Manual Installation
4~~~~~~~~~~~~~~~~~~~
5
6Install and configure components
7--------------------------------
8
91. Install the packages in any way you prefer
10 (**github+setup.py** / **pip** / **packages**)
11
122. Create the service credentials
13
14 .. include:: credentials-creation.rst
15
163. Create database
17
18 .. include:: database-creation.rst
19
20 There is a script creating 'ec2api' database that is accessible
21 only on localhost by user 'ec2api' with password 'ec2api'.
22 https://github.com/openstack/ec2-api/blob/master/tools/db/ec2api-db-setup
23
244. Create endpoints:
25
26 .. include:: endpoints-creation.rst
27
285. Create configuration files ``/etc/ec2api/api-paste.ini``
29 (can be copied from
30 https://github.com/openstack/ec2-api/blob/master/etc/ec2api/api-paste.ini)
31
32 and ``/etc/ec2api/ec2api.conf``
33
34 .. include:: configuration.rst
35
366. Configure metadata:
37
38 .. include:: metadata-configuration.rst
39
407. Start the services as binaries
41
42 .. code-block:: console
43
44 $ /usr/local/bin/ec2-api
45 $ /usr/local/bin/ec2-api-metadata
46
47 or set up as Linux services.
diff --git a/doc/source/install/install-sh.rst b/doc/source/install/install-sh.rst
new file mode 100644
index 0000000..268b6c2
--- /dev/null
+++ b/doc/source/install/install-sh.rst
@@ -0,0 +1,38 @@
1.. _install-sh:
2
3Installation by install.sh
4~~~~~~~~~~~~~~~~~~~~~~~~~~~
5
6Install and configure components
7--------------------------------
8
9Install the packages:
10
11.. code-block:: console
12
13 # apt-get update
14 # git clone https://github.com/openstack/ec2-api.git
15 # cd ec2-api
16
17Run install.sh
18
19The EC2 API service gets installed on port 8788 by default. It can be changed
20before the installation in ``/etc/ec2api/ec2api.conf`` configuration file.
21
22:ref:`configuring`.
23
24The services afterwards can be started as binaries:
25
26.. code-block:: console
27
28 $ /usr/local/bin/ec2-api
29 $ /usr/local/bin/ec2-api-metadata
30
31or set up as Linux services.
32
33.. include:: endpoints-creation.rst
34
35Configuring OpenStack for EC2 API metadata service
36---------------------------------------------------
37
38.. include:: metadata-configuration.rst
diff --git a/doc/source/install/install-ubuntu.rst b/doc/source/install/install-ubuntu.rst
index d73f830..7e16c42 100644
--- a/doc/source/install/install-ubuntu.rst
+++ b/doc/source/install/install-ubuntu.rst
@@ -1,64 +1,19 @@
1.. _install-ubuntu: 1.. _install-ubuntu:
2 2
3Installation on existing OpenStack deployment
4~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
5 3
6This section describes how to install and configure the ec2-api 4Install and configure
7service for Ubuntu (LTS). 5~~~~~~~~~~~~~~~~~~~~~
8 6
9Install and configure components 7This section describes how to install and configure the ec2-api service on the
10-------------------------------- 8controller node for Ubuntu (LTS).
11 9
12Install the packages: 10It assumes that you already have a working OpenStack environment with
11at least the following components installed: Compute, Networking, Block Storage,
12Identity, Image.
13 13
14.. code-block:: console 14.. toctree::
15 :maxdepth: 1
15 16
16 # apt-get update 17 install-sh.rst
17 # git clone https://github.com/openstack/ec2-api.git 18 install-manual.rst
18 # cd ec2-api 19 install-devstack.rst
19
20Run install.sh
21
22The EC2 API service gets installed on port 8788 by default. It can be changed
23before the installation in install.sh script.
24
25The services afterwards can be started as binaries:
26
27::
28
29 /usr/local/bin/ec2-api
30 /usr/local/bin/ec2-api-metadata
31
32or set up as Linux services.
33
34.. include:: endpoints-creation.rst
35
36Configuring OpenStack for EC2 API metadata service
37--------------------------------------------------
38
39To configure OpenStack for EC2 API metadata service:
40
41for Nova-network add:
42
43.. code-block:: console
44
45 # [DEFAULT]
46 # metadata_port = 8789
47 # [neutron]
48 # service_metadata_proxy = True
49
50to ``/etc/nova.conf``
51
52then restart nova-metadata (can be run as part of nova-api service) and
53nova-network services.
54
55for Neutron add:
56
57.. code-block:: console
58
59 # [DEFAULT]
60 # nova_metadata_port = 8789
61
62to ``/etc/neutron/metadata_agent.ini``
63
64then restart neutron-metadata service.
diff --git a/doc/source/install/install.rst b/doc/source/install/install.rst
deleted file mode 100644
index 92bf62c..0000000
--- a/doc/source/install/install.rst
+++ /dev/null
@@ -1,24 +0,0 @@
1.. _install:
2
3Install and configure
4~~~~~~~~~~~~~~~~~~~~~
5
6This section describes how to install and configure the ec2-api service on the
7controller node.
8
9This section assumes that you already have a working OpenStack environment with
10at least the following components installed: Compute, Networking, Block Storage,
11Identity, Image.
12
13.. toctree::
14 :maxdepth: 2
15
16 install-ubuntu.rst
17
18Additional steps:
19
20.. toctree::
21 :maxdepth: 2
22
23 database-creation.rst
24 credentials-creation.rst
diff --git a/doc/source/install/metadata-configuration.rst b/doc/source/install/metadata-configuration.rst
new file mode 100644
index 0000000..2e0d826
--- /dev/null
+++ b/doc/source/install/metadata-configuration.rst
@@ -0,0 +1,14 @@
1EC2 metadata is built in between the nova-metadata and the neutron-metadata,
2so we need to configure Neutron so that it sends requests to ec2-api-metadata,
3not to the nova.
4
5To configure OpenStack for EC2 API metadata service for Neutron add:
6
7.. code-block:: ini
8
9 [DEFAULT]
10 nova_metadata_port = 8789
11
12to ``/etc/neutron/metadata_agent.ini``
13
14then restart neutron-metadata service.
diff --git a/doc/source/install/verify.rst b/doc/source/install/verify.rst
index 53cd020..79be1f4 100644
--- a/doc/source/install/verify.rst
+++ b/doc/source/install/verify.rst
@@ -14,7 +14,7 @@ Verify operation of the ec2-api service.
14 14
15 .. code-block:: console 15 .. code-block:: console
16 16
17 $ . admin-openrc 17 $ . openrc admin admin
18 18
19#. List service components to verify successful launch and registration 19#. List service components to verify successful launch and registration
20 of each process: 20 of each process:
@@ -24,8 +24,14 @@ Verify operation of the ec2-api service.
24 $ openstack service list 24 $ openstack service list
25 25
26 26
27#. Download aws cli from Amazon. Create configuration file for aws cli in your 27#. Install aws cli.
28 home directory ``~/.aws/config``: 28
29 .. code-block:: console
30
31 # pip install awscli --upgrade --user
32
33#. Create configuration file for aws cli in your home directory
34 ``~/.aws/config`` or by "**aws configure**" command:
29 35
30 .. code-block:: console 36 .. code-block:: console
31 37
@@ -36,7 +42,7 @@ Verify operation of the ec2-api service.
36 42
37 Change the aws_access_key_id and aws_secret_acces_key above to the values 43 Change the aws_access_key_id and aws_secret_acces_key above to the values
38 appropriate for your cloud (can be obtained by 44 appropriate for your cloud (can be obtained by
39 **"openstack ec2 credentials list"** command). 45 "**openstack ec2 credentials list**" command).
40 46
41#. Run aws cli commands using new EC2 API endpoint URL (can be obtained from 47#. Run aws cli commands using new EC2 API endpoint URL (can be obtained from
42 keystone with the new port 8788) like this: 48 keystone with the new port 8788) like this: