github.com/chasestarr/deis@v1.13.5-0.20170519182049-1d9e59fbdbfc/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:`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  /deis/logs/host                          IP address of the host running logger
    34  =============================            =================================================================================
    35  
    36  Settings used by controller
    37  ---------------------------
    38  The following etcd keys are used by the controller component.
    39  
    40  ====================================      ======================================================
    41  setting                                   description
    42  ====================================      ======================================================
    43  /deis/controller/registrationMode         set registration to "enabled", "disabled", or "admin_only" (default: "enabled")
    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/database/host                       host of the database component (set by database)
    48  /deis/database/port                       port of the database component (set by database)
    49  /deis/database/engine                     database engine (set by database)
    50  /deis/database/name                       database name (set by database)
    51  /deis/database/user                       database user (set by database)
    52  /deis/database/password                   database password (set by database)
    53  /deis/registry/host                       host of the registry component (set by registry)
    54  /deis/registry/port                       port of the registry component (set by registry)
    55  /deis/registry/protocol                   protocol of the registry component (set by registry)
    56  ====================================      ======================================================
    57  
    58  Using a custom controller image
    59  -------------------------------
    60  You can use a custom Docker image for the controller component instead of the image
    61  supplied with Deis:
    62  
    63  .. code-block:: console
    64  
    65      $ deisctl config controller set image=myaccount/myimage:latest
    66  
    67  This will pull the image from the public Docker registry. You can also pull from a private
    68  registry:
    69  
    70  .. code-block:: console
    71  
    72      $ deisctl config controller set image=registry.mydomain.org:5000/myaccount/myimage:latest
    73  
    74  Be sure that your custom image functions in the same way as the `stock controller image`_ shipped with
    75  Deis. Specifically, ensure that it sets and reads appropriate etcd keys.
    76  
    77  .. _`stock controller image`: https://github.com/deis/deis/tree/master/controller
    78  
    79  Unit hostname
    80  -------------
    81  Per default, Docker automatically generates a hostname for your application unit, such as:
    82  ``5c149b397cd6``. Auto generated hostnames is not always preferred. For instance,
    83  New Relic would classify each Docker container as an unique server since they use hostname
    84  for grouping applications running on the same server together.
    85  
    86  Deis supports configuring hostname assignment through the ``unitHostname`` setting.
    87  You can change the assignment solution using the following command:
    88  
    89  .. code-block:: console
    90  
    91      $ deisctl config controller set unitHostname=application
    92  
    93  The valid ``unitHostname`` values are:
    94  
    95  default
    96      Docker will generate the hostname. Example: ``5c149b397cd6``
    97  
    98  application
    99      The hostname is assigned based on the unit name. Example: ``dancing-cat.v2.web.1``
   100  
   101  server
   102      The hostname is assigned based on the CoreOS hostname. Example:
   103      ``ip-10-21-2-168.eu-west-1.compute.internal``
   104  
   105  .. note::
   106  
   107      Changes to ``/deis/controller/unitHostname`` requires either pushing a new build to
   108      every application or scaling them down and up.
   109      The change is only detected when a container unit is deployed.
   110  
   111  Changing the Registration Mode
   112  ------------------------------
   113  
   114  By default, anybody can register a user with the Deis controller.
   115  However, this is often undesirable from a security point of view.
   116  
   117  Deis supports configuring the registration mode through the ``registrationMode`` setting.
   118  
   119  Registration Modes
   120  ^^^^^^^^^^^^^^^^^^
   121  ========== =========================================================
   122  mode       description
   123  ========== =========================================================
   124  enabled    Default. Anybody can register a user with the controller.
   125  disabled   Nobody can register a user with the controller.
   126  admin_only Only admins can register a user with the controller.
   127  ========== =========================================================
   128  
   129  This will set the registration mode to admin_only.
   130  
   131  .. code-block:: console
   132  
   133      $ deisctl config controller set registrationMode="admin_only"
   134  
   135  Using a LDAP Auth
   136  -----------------
   137  The Deis controller supports Single Sign On access control, for now Deis is able to authenticate using LDAP or Active Directory.
   138  
   139  Settings used by LDAP
   140  ^^^^^^^^^^^^^^^^^^^^^
   141  =========================================           =================================================================================
   142  setting                                             description
   143  =========================================           =================================================================================
   144  /deis/controller/auth/ldap/endpoint                 The full LDAP endpoint. (Ex.: ldap://ldap.company.com)
   145  /deis/controller/auth/ldap/bind/dn                  Full user for bind. (Ex.: user@company.com. For Anonymous bind leave blank)
   146  /deis/controller/auth/ldap/bind/password            Password of the user for bind. (For anonymous bind leave blank)
   147  /deis/controller/auth/ldap/user/basedn              The BASE DN where your LDAP Users are placed. (Ex.: OU=TeamX,DC=Company,DC=com)
   148  /deis/controller/auth/ldap/user/filter              The field that we will match with username of Deis. (In most cases is uuid, AD uses sAMAccountName)
   149  /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)
   150  /deis/controller/auth/ldap/group/filter             The field that we will locate your groups with LDAPSearch. (In most cases is objectClass)
   151  /deis/controller/auth/ldap/group/type               The Groups type of LDAP. (Use groupOfNames if you don't know)
   152  =========================================           =================================================================================
   153  
   154  Configuring LDAP on Controller
   155  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
   156  
   157  .. important::
   158  
   159      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.
   160      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.
   161  
   162  
   163  .. code-block:: console
   164  
   165      $ deisctl config controller set auth/ldap/endpoint=<ldap-endpoint>
   166      $ deisctl config controller set auth/ldap/bind/dn=<bind-dn-full-user>
   167      $ deisctl config controller set auth/ldap/bind/password=<bind-dn-user-password>
   168      $ deisctl config controller set auth/ldap/user/basedn=<user-base-dn>
   169      $ deisctl config controller set auth/ldap/user/filter=<user-filter>
   170      $ deisctl config controller set auth/ldap/group/basedn=<group-base-dn>
   171      $ deisctl config controller set auth/ldap/group/filter=<group-filter>
   172      $ deisctl config controller set auth/ldap/group/type=<group-type>
   173  
   174  .. note::
   175  
   176      You can set a LDAP user as admin by using ``deis perms:create <LDAP User> --admin`` with the admin created before.
   177  
   178  .. note::
   179  
   180      LDAP support was contributed by community member Pedro Spagiari (`@phspagiari <http://github.com/phspagiari/>`_) and is unsupported by the Deis core team.