en-US/aws-ec2-user-setup.xml

<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "cloudstack.ent">
%BOOK_ENTITIES;
]>

<!-- Licensed to the Apache Software Foundation (ASF) under one
 or more contributor license agreements.  See the NOTICE file
 distributed with this work for additional information
 regarding copyright ownership.  The ASF licenses this file
 to you under the Apache License, Version 2.0 (the
 "License"); you may not use this file except in compliance
 with the License.  You may obtain a copy of the License at
 
   http://www.apache.org/licenses/LICENSE-2.0
 
 Unless required by applicable law or agreed to in writing,
 software distributed under the License is distributed on an
 "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 KIND, either express or implied.  See the License for the
 specific language governing permissions and limitations
 under the License.
-->
<section id="aws-ec2-user-setup">
  <title>AWS API User Setup</title>
  <para>In general, users need not be aware that they are using a translation service provided by &PRODUCT;.
    They only need to send AWS API calls to &PRODUCT;'s endpoint, and it will translate the calls to the native &PRODUCT; API. Users of the Amazon EC2 compatible interface will be able to keep their existing EC2 tools
    and scripts and use them with their &PRODUCT; deployment, by specifying the endpoint of the
    management server and using the proper user credentials. In order to do this, each user must
    perform the following configuration steps: </para>
  <para>
    <itemizedlist>
      <listitem>
        <para>Generate user credentials.</para>
      </listitem>
      <listitem>
        <para>Register with the service.</para>
      </listitem>
      <listitem>
        <para>For convenience, set up environment variables for the EC2 SOAP command-line tools.</para>
      </listitem>
    </itemizedlist>
  </para>
  <section id="aws-ec2-user-registration">
    <title>AWS API User Registration</title>
    <para>Each user must perform a one-time registration.  The user follows these steps:</para>
    <orderedlist>
      <listitem id="obtain-access-secret-keys">
          <para>Obtain the following by looking in the &PRODUCT; UI, using the API, or asking the cloud administrator:
          </para>
          <itemizedlist>
              <listitem><para>The &PRODUCT; server's publicly available DNS name or IP address</para></listitem>
              <listitem><para>The user account's Access key and Secret key</para></listitem>
          </itemizedlist>
      </listitem>
      <listitem>
          <para>Generate a private key and a self-signed X.509 certificate. The user substitutes their own desired storage location for /path/to/… below.
          </para>
          <para>
              <programlisting>$ openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout /path/to/private_key.pem -out /path/to/cert.pem</programlisting>
          </para>
      </listitem>
      <listitem>
          <para>Register the user X.509 certificate and Access/Secret keys with the AWS compatible service. 
      If you have the source code of &PRODUCT; go to the awsapi-setup/setup directory and use the Python script 
      cloudstack-aws-api-register. If you do not have the source then download the script using the following command.
          </para>
          <para>
              <programlisting>wget -O cloudstack-aws-api-register <ulink url="https://git-wip-us.apache.org/repos/asf?p=cloudstack.git;a=blob_plain;f=awsapi-setup/setup/cloudstack-aws-api-register;hb=4.1">"https://git-wip-us.apache.org/repos/asf?p=cloudstack.git;a=blob_plain;f=awsapi-setup/setup/cloudstack-aws-api-register;hb=4.1"</ulink>
              </programlisting>
          </para>
          <para> Then execute it, using the access and secret keys that were obtained in step <xref linkend="obtain-access-secret-keys"/>. An example is shown below.</para>
          <para>
              <programlisting>$ cloudstack-aws-api-register --apikey=<replaceable>User’s &PRODUCT; API key</replaceable> --secretkey=<replaceable>User’s &PRODUCT; Secret key</replaceable> --cert=<replaceable>/path/to/cert.pem</replaceable> --url=http://<replaceable>&PRODUCT;.server</replaceable>:7080/awsapi</programlisting>
          </para>
      </listitem>
    </orderedlist>
   <note>
     <para>
       A user with an existing AWS certificate could choose to use the same certificate with &PRODUCT;, but note that the       certificate would be uploaded to the &PRODUCT; management server database.
     </para>
   </note>
  </section>
  <section id="aws-api-tools-setup">
      <title>AWS API Command-Line Tools Setup</title>
      <para>To use the EC2 command-line tools, the user must perform these steps:</para>
      <orderedlist>
          <listitem>
              <para>Be sure you have the right  version of EC2 Tools.
          The supported version is available at <ulink url="http://s3.amazonaws.com/ec2-downloads/ec2-api-tools-1.3-62308.zip">http://s3.amazonaws.com/ec2-downloads/ec2-api-tools-1.3-62308.zip</ulink>.
              </para>
          </listitem>
          <listitem>
              <para>Set up the EC2 environment variables.  This can be done every time you use the service or you can set them up in the proper shell profile. Replace the endpoint (i.e EC2_URL) with the proper address of your &PRODUCT; management server and port. In a bash shell do the following.
              </para>
              <programlisting>
                  $ export EC2_CERT=/path/to/cert.pem
                  $ export EC2_PRIVATE_KEY=/path/to/private_key.pem
                  $ export EC2_URL=http://localhost:7080/awsapi
                  $ export EC2_HOME=/path/to/EC2_tools_directory
              </programlisting>
          </listitem>
      </orderedlist>
  </section>
</section>