github.com/technosophos/deis@v1.7.1-0.20150915173815-f9005256004b/docs/customizing_deis/controller_settings.rst (about)

     1  :title: Customizing controller
     2  :description: Learn how to tune custom Deis settings.
     3  
     4  .. _controller_settings:
     5  
     6  Customizing controller
     7  =========================
     8  The following settings are tunable for the :ref:`controller` component.
     9  
    10  Dependencies
    11  ------------
    12  Requires: :ref:`cache <cache_settings>`, :ref:`database <database_settings>`, :ref:`registry <registry_settings>`
    13  
    14  Required by: :ref:`router <router_settings>`
    15  
    16  Considerations: none
    17  
    18  Settings set by controller
    19  --------------------------
    20  The following etcd keys are set by the controller component, typically in its /bin/boot script.
    21  
    22  =============================            =================================================================================
    23  setting                                  description
    24  =============================            =================================================================================
    25  /deis/controller/host                    IP address of the host running controller
    26  /deis/controller/port                    port used by the controller service (default: 8000)
    27  /deis/controller/protocol                protocol for controller (default: http)
    28  /deis/controller/secretKey               used for secrets (default: randomly generated)
    29  /deis/controller/builderKey              used by builder to authenticate with the controller (default: randomly generated)
    30  /deis/controller/unitHostname            See `Unit hostname`_. (default: "default")
    31  /deis/builder/users/*                    stores user SSH keys (used by builder)
    32  /deis/domains/*                          domain configuration for applications (used by router)
    33  =============================            =================================================================================
    34  
    35  Settings used by controller
    36  ---------------------------
    37  The following etcd keys are used by the controller component.
    38  
    39  ====================================      ======================================================
    40  setting                                   description
    41  ====================================      ======================================================
    42  /deis/controller/registrationMode         set registration to "enabled", "disabled", or "admin_only" (default: "enabled")
    43  /deis/controller/schedulerModule          scheduler backend (default: "fleet")
    44  /deis/controller/subdomain                subdomain used by the router for API requests (default: "deis")
    45  /deis/controller/webEnabled               enable controller web UI (default: 0)
    46  /deis/controller/workers                  number of web worker processes (default: CPU cores * 2 + 1)
    47  /deis/cache/host                          host of the cache component (set by cache)
    48  /deis/cache/port                          port of the cache component (set by cache)
    49  /deis/database/host                       host of the database component (set by database)
    50  /deis/database/port                       port of the database component (set by database)
    51  /deis/database/engine                     database engine (set by database)
    52  /deis/database/name                       database name (set by database)
    53  /deis/database/user                       database user (set by database)
    54  /deis/database/password                   database password (set by database)
    55  /deis/registry/host                       host of the registry component (set by registry)
    56  /deis/registry/port                       port of the registry component (set by registry)
    57  /deis/registry/protocol                   protocol of the registry component (set by registry)
    58  ====================================      ======================================================
    59  
    60  Using a custom controller image
    61  -------------------------------
    62  You can use a custom Docker image for the controller component instead of the image
    63  supplied with Deis:
    64  
    65  .. code-block:: console
    66  
    67      $ deisctl config controller set image=myaccount/myimage:latest
    68  
    69  This will pull the image from the public Docker registry. You can also pull from a private
    70  registry:
    71  
    72  .. code-block:: console
    73  
    74      $ deisctl config controller set image=registry.mydomain.org:5000/myaccount/myimage:latest
    75  
    76  Be sure that your custom image functions in the same way as the `stock controller image`_ shipped with
    77  Deis. Specifically, ensure that it sets and reads appropriate etcd keys.
    78  
    79  .. _`stock controller image`: https://github.com/deis/deis/tree/master/controller
    80  
    81  Unit hostname
    82  -------------
    83  Per default, Docker automatically generates a hostname for your application unit, such as:
    84  ``5c149b397cd6``. Auto generated hostnames is not always preferred. For instance,
    85  New Relic would classify each Docker container as an unique server since they use hostname
    86  for grouping applications running on the same server together.
    87  
    88  Deis supports configuring hostname assignment through the ``unitHostname`` setting.
    89  You can change the assignment solution using the following command:
    90  
    91  .. code-block:: console
    92  
    93      $ deisctl config controller set unitHostname=application
    94  
    95  The valid ``unitHostname`` values are:
    96  
    97  default
    98      Docker will generate the hostname. Example: ``5c149b397cd6``
    99  
   100  application
   101      The hostname is assigned based on the unit name. Example: ``dancing-cat.v2.web.1``
   102  
   103  server
   104      The hostname is assigned based on the CoreOS hostname. Example:
   105      ``ip-10-21-2-168.eu-west-1.compute.internal``
   106  
   107  .. note::
   108  
   109      Changes to ``/deis/controller/unitHostname`` requires either pushing a new build to
   110      every application or scaling them down and up.
   111      The change is only detected when a container unit is deployed.
   112  
   113  Changing the Registration Mode
   114  ------------------------------
   115  
   116  By default, anybody can register a user with the Deis controller.
   117  However, this is often undesirable from a security point of view.
   118  
   119  Deis supports configuring the registration mode through the ``registrationMode`` setting.
   120  
   121  Registration Modes
   122  ^^^^^^^^^^^^^^^^^^
   123  ========== =========================================================
   124  mode       description
   125  ========== =========================================================
   126  enabled    Default. Anybody can register a user with the controller.
   127  disabled   Nobody can register a user with the controller.
   128  admin_only Only admins can register a user with the controller.
   129  ========== =========================================================
   130  
   131  This will set the registration mode to admin_only.
   132  
   133  .. code-block:: console
   134  
   135      $ deisctl config controller set registrationMode="admin_only"
   136  
   137  Using a LDAP Auth
   138  -----------------
   139  The Deis controller supports Single Sign On access control, for now Deis is able to authenticate using LDAP or Active Directory.
   140  
   141  Settings used by LDAP
   142  ^^^^^^^^^^^^^^^^^^^^^
   143  =========================================           =================================================================================
   144  setting                                             description
   145  =========================================           =================================================================================
   146  /deis/controller/auth/ldap/endpoint                 The full LDAP endpoint. (Ex.: ldap://ldap.company.com)
   147  /deis/controller/auth/ldap/bind/dn                  Full user for bind. (Ex.: user@company.com. For Anonymous bind leave blank)
   148  /deis/controller/auth/ldap/bind/password            Password of the user for bind. (For anonymous bind leave blank)
   149  /deis/controller/auth/ldap/user/basedn              The BASE DN where your LDAP Users are placed. (Ex.: OU=TeamX,DC=Company,DC=com)
   150  /deis/controller/auth/ldap/user/filter              The field that we will match with username of Deis. (In most cases is uuid, AD uses sAMAccountName)
   151  /deis/controller/auth/ldap/group/basedn             The BASE DN where the groups of your LDAP are are located. (Ex.: OU=Groups,OU=TeamX,DC=Company,DC=com)
   152  /deis/controller/auth/ldap/group/filter             The field that we will locate your groups with LDAPSearch. (In most cases is objectClass)
   153  /deis/controller/auth/ldap/group/type               The Groups type of LDAP. (Use groupOfNames if you don't know)
   154  =========================================           =================================================================================
   155  
   156  Configuring LDAP on Controller
   157  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   158  
   159  .. important::
   160  
   161      It's important that you register the first user of the default auth in order to have an admin ( see :ref:`Register a User <register-user>` ) without this you don't have any deis admin because LDAP users haven't this permission, you will need to set this later.
   162      After this you need to disable the registration ( see :ref:`disable_user_registration` ) avoiding that "ghost" users register and access your Deis. The auth model of controller by default allows multiple source auths so LDAP and non-LDAP users will be able to login.
   163  
   164  
   165  .. code-block:: console
   166  
   167      $ deisctl config controller set auth/ldap/endpoint=<ldap-endpoint>
   168      $ deisctl config controller set auth/ldap/bind/dn=<bind-dn-full-user>
   169      $ deisctl config controller set auth/ldap/bind/password=<bind-dn-user-password>
   170      $ deisctl config controller set auth/ldap/user/basedn=<user-base-dn>
   171      $ deisctl config controller set auth/ldap/user/filter=<user-filter>
   172      $ deisctl config controller set auth/ldap/group/basedn=<group-base-dn>
   173      $ deisctl config controller set auth/ldap/group/filter=<group-filter>
   174      $ deisctl config controller set auth/ldap/group/type=<group-type>
   175  
   176  .. note::
   177  
   178      You can set a LDAP user as admin by using ``deis perms:create <LDAP User> --admin`` with the admin created before.
   179  
   180  .. note::
   181  
   182      LDAP support was contributed by community member Pedro Spagiari (`@phspagiari <http://github.com/phspagiari/>`_) and is unsupported by the Deis core team.