github.com/chasestarr/deis@v1.13.5-0.20170519182049-1d9e59fbdbfc/docs/installing_deis/linode.rst (about)

     1  :title: Installing Deis on Linode
     2  :description: How to provision a multi-node Deis cluster on Linode
     3  
     4  .. _deis_on_linode:
     5  
     6  Linode
     7  ======
     8  
     9  In this tutorial, we will show you how to set up your own 3-node cluster on Linode.
    10  
    11  Please :ref:`get the source <get_the_source>` and refer to the scripts in `contrib/linode`_
    12  while following this documentation.
    13  
    14  .. important::
    15  
    16      Linode support is untested by the Deis team, so we rely on the community to
    17      improve this documentation and fix bugs. We greatly appreciate the help!
    18  
    19  
    20  Prerequisites
    21  -------------
    22  
    23  Before we can begin to provision a cluster on Linode, let's get a few things squared away.
    24  
    25  
    26  Enable KVM Hypervisor
    27  ^^^^^^^^^^^^^^^^^^^^^
    28  
    29  Navigate to the `Linode Account Settings`_ page and change the Hypervisor Preference to ``KVM``.
    30  
    31  Although it is possible to provision CoreOS under Xen on Linode it is much more difficult and
    32  the tools included only work with the KVM Hypervisor.
    33  
    34  
    35  Obtain Linode API Key
    36  ^^^^^^^^^^^^^^^^^^^^^
    37  
    38  Next, navigate to the `Linode API Keys`_ page and generate an API key. Take note of the key,
    39  as you will need it later when you provision your cluster.
    40  
    41  
    42  Install Python and Dependencies
    43  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
    44  
    45  The scripts used to provision the cluster are written for Python 2.7 and require a few
    46  dependencies be installed with the `pip`_ package manager. If you are on OS X or Linux you
    47  likely have these already available.
    48  
    49  Lets install our dependencies:
    50  
    51  .. code-block:: console
    52  
    53      $ pip install -r contrib/linode/requirements.txt
    54  
    55  
    56  Generate SSH Key
    57  ^^^^^^^^^^^^^^^^
    58  
    59  If you don't already have a SSH key, the following command will generate
    60  a new keypair named "deis":
    61  
    62  .. code-block:: console
    63  
    64      $ ssh-keygen -q -t rsa -f ~/.ssh/deis -N '' -C deis
    65  
    66  
    67  Check System Requirements
    68  -------------------------
    69  
    70  Please refer to :ref:`system-requirements` for resource considerations when choosing a Linode
    71  plan to run Deis. A Deis cluster must have 3 or more nodes. See :ref:`cluster-size` for more details.
    72  
    73  
    74  Create Cloud Init
    75  -----------------
    76  
    77  Create your cloud init file using Deis' ``contrib/linode/create-linode-user-data.py`` script.
    78  
    79  First navigate to the ``contrib/linode`` directory:
    80  
    81  .. code-block:: console
    82  
    83      $ cd contrib/linode
    84  
    85  Then, create the ``linode-user-data.yaml`` file:
    86  
    87  .. code-block:: console
    88  
    89      $ ./create-linode-user-data.py --public-key /path/to/key/deis.pub
    90  
    91  It is possible to specify multiple authorized keys and/or specify an etcd token to use for the cluster.
    92  See the full command usage below:
    93  
    94  .. code-block:: console
    95  
    96      usage: create-linode-user-data.py [-h] --public-key PUBLIC_KEY_FILES
    97                                    [--etcd-token ETCD_TOKEN]
    98  
    99      Create Linode User Data
   100  
   101      optional arguments:
   102        -h, --help            show this help message and exit
   103        --public-key PUBLIC_KEY_FILES
   104                              Authorized SSH Keys
   105        --etcd-token ETCD_TOKEN
   106                              Etcd Token
   107  
   108  Provision Cluster
   109  -----------------
   110  
   111  The time has finally come to provision our cluster and all it takes is a single command!
   112  
   113  .. code-block:: console
   114  
   115      $ ./provision-linode-cluster.py --api-key=YOUR_LINODE_API_KEY provision
   116  
   117  This command will create a 3 node cluster of Linode 4096s in Dallas TX, however by passing additional
   118  arguments you can specify the data center, size of nodes, number of nodes, and a bunch more:
   119  
   120  .. code-block:: console
   121  
   122      usage: provision-linode-cluster.py provision [-h] [--num NUM_NODES]
   123                                                   [--name-prefix NODE_NAME_PREFIX]
   124                                                   [--display-group NODE_DISPLAY_GROUP]
   125                                                   [--plan NODE_PLAN]
   126                                                   [--datacenter NODE_DATA_CENTER]
   127                                                   [--cloud-config CLOUD_CONFIG]
   128                                                   [--coreos-version COREOS_VERSION]
   129                                                   [--coreos-channel COREOS_CHANNEL]
   130  
   131      optional arguments:
   132        -h, --help            show this help message and exit
   133        --num NUM_NODES       Number of nodes to provision
   134        --name-prefix NODE_NAME_PREFIX
   135                              Node name prefix
   136        --display-group NODE_DISPLAY_GROUP
   137                              Node display group
   138        --plan NODE_PLAN      Node plan id. Use list-plans to find the id.
   139        --datacenter NODE_DATA_CENTER
   140                              Node data center id. Use list-data-centers to find the
   141                              id.
   142        --cloud-config CLOUD_CONFIG
   143                              CoreOS cloud config user-data file
   144        --coreos-version COREOS_VERSION
   145                              CoreOS version number to install
   146        --coreos-channel COREOS_CHANNEL
   147                              CoreOS channel to install from
   148  
   149  
   150  Additionally, the provision tool contains two utilities to list available data centers and plans that
   151  can help find the command argument values.
   152  
   153  .. code-block:: console
   154  
   155      $ ./provision-linode-cluster.py --api-key=YOUR_LINODE_API_KEY list-data-centers
   156  
   157  .. code-block:: console
   158  
   159      $ ./provision-linode-cluster.py --api-key=YOUR_LINODE_API_KEY list-plans
   160  
   161  
   162  Apply Security Group Settings
   163  -----------------------------
   164  
   165  Because Linode does not have a security group feature, we'll need to add some custom
   166  ``iptables`` rules so our components are not accessible to the outside world.
   167  
   168  
   169  If you are on the Linode private network, run:
   170  
   171  .. code-block:: console
   172  
   173      $ ./apply-firewall.py --private-key /path/to/key/deis
   174  
   175  
   176  If you are outside the private network, you will have to manually specify the public ip address of
   177  each host. To do so, run:
   178  
   179  .. code-block:: console
   180  
   181      $ ./apply-firewall.py --private-key /path/to/key/deis --hosts 1.2.3.4 11.22.33.44 111.222.33.44
   182  
   183      
   184  Or, you can provide the display group (NOTE: the default display group is ``deis``) to search for the
   185  nodes using the Linode API, by running:
   186  
   187  .. code-block:: console
   188  
   189      $ ./apply-firewall.py --private-key /path/to/key/deis --api-key YOUR_LINODE_API_KEY --display-group YOUR_DISPLAY_GROUP
   190  
   191  
   192  The script will use either the Linode API or the etcd discovery url to find all of the nodes in your
   193  cluster and create iptables rules to allow connections between nodes while blocking outside connections
   194  automatically. Note that when discovering node ips, the ``--display-group`` parameter has highest priority,
   195  then manual specification via ``--nodes`` and ``--hosts`` (i.e. public and private ips), then the etcd
   196  discovery url via parameter ``--display-url`` or the ``linode-user-data.yaml`` file. Full command usage:
   197  
   198  .. code-block:: console
   199  
   200      usage: apply-firewall.py [-h] --private-key PRIVATE_KEY [--private]
   201                               [--adding-new-nodes]
   202                               [--discovery-url DISCOVERY_URL]
   203                               [--display-group DISPLAY_GROUP]
   204                               [--hosts HOSTS [HOSTS ...]]
   205                               [--nodes HOSTS [HOSTS ...]]
   206  
   207      Apply a "Security Group" to a Deis cluster
   208  
   209      optional arguments:
   210        -h, --help            show this help message and exit
   211        --private-key PRIVATE_KEY
   212                              Cluster SSH Private Key
   213        --private             Only allow access to the cluster from the private
   214                              network
   215        --adding-new-nodes    When adding new nodes to existing cluster, allows access to etcd
   216        --display-group DISPLAY_GROUP
   217                              Linode display group for nodes 
   218        --discovery-url DISCOVERY_URL
   219                              Etcd discovery url
   220        --hosts HOSTS [HOSTS ...]
   221                              The public IP addresses of the hosts
   222        --nodes HOSTS [HOSTS ...]
   223                              The private IP addresses of the hosts 
   224  
   225  
   226  Install Deis Platform
   227  ---------------------
   228  
   229  Now that you've finished provisioning a cluster, please refer to :ref:`install_deis_platform` to
   230  start installing the platform.
   231  
   232  
   233  Adding Nodes to an Existing Cluster
   234  -----------------------------------
   235  
   236  When adding one or more nodes to an existing CoreOS setup, ``etcd`` will be `added as a proxy to
   237  the existing cluster`_. The setup of a proxy requires access to ports 2379 and 2380 of the existing
   238  nodes in the cluster.
   239  
   240  In order to open up these ports, before cluster provisioning, run:
   241  
   242  .. code-block:: console
   243  
   244      $ ./apply-firewall.py --private-key /path/to/key/deis --hosts 1.2.3.4 11.22.33.44 111.222.33.44
   245                            --adding-new-nodes
   246  
   247      
   248  Then provision the cluster as described above and afterwards reapply the firewall using
   249  ``./apply-firewall.py`` without the ``--adding-new-nodes`` parameter.
   250  
   251  
   252  .. _`added as a proxy to the existing cluster`: https://coreos.com/etcd/docs/latest/clustering.html#public-etcd-discovery-service
   253  .. _`contrib/linode`: https://github.com/deis/deis/tree/master/contrib/linode
   254  .. _`Linode Account Settings`: https://manager.linode.com/account/settings
   255  .. _`Linode API Keys`: https://manager.linode.com/profile/api
   256  .. _`pip`: https://pip.pypa.io/en/stable/
   257