Remove the 'debops.bootstrap' Ansible role

parent 43516a9e
......@@ -199,14 +199,6 @@ stages:
# --- b --- [[[2
'bootstrap role':
<<: *test_role_2nd_deps
variables:
JANE_TEST_PLAY: '${DEBOPS_PLAYBOOKS}/bootstrap.yml'
JANE_INVENTORY_HOSTVARS: 'ansible_become=true'
JANE_DIFF_PATTERN: '.*/debops.bootstrap/.*'
JANE_LOG_PATTERN: '\[debops\.bootstrap\]'
# At the moment BoxBackup role is broken, needs to be updated.
#'boxbackup role':
# <<: *test_role_1st_deps
......
......@@ -307,6 +307,10 @@ Removed
now implemented by the :ref:`debops.users` role, custom bind mounts can be
defined using the :ref:`debops.mount` role.
- The ``debops.bootstrap`` Ansible role has been removed. Its replacement is
the :ref:`debops.system_users` which is used to manage system administrator
accounts, via the ``common.yml`` playbook and the bootstrap playbooks.
Fixed
~~~~~
......@@ -616,7 +620,7 @@ Removed
``ansible_local.uuid`` local facts, respectively.
- The hostname and domain configuration has been removed from the
:ref:`debops.bootstrap` role. This functionality is now handled by the
``debops.bootstrap`` role. This functionality is now handled by the
:ref:`debops.netbase` role, which has been included in the bootstrap
playbook. The relevant inventory variables have been renamed, check the
:ref:`upgrade_notes` for details.
......@@ -828,7 +832,7 @@ Removed
Ansible role.
- [debops.bootstrap] The :command:`sudo` configuration has been removed from
the :ref:`debops.bootstrap` role. The ``bootstrap.yml`` playbook now includes
the ``debops.bootstrap`` role. The ``bootstrap.yml`` playbook now includes
the :ref:`debops.sudo` role which configures :command:`sudo` service.
- [debops.bootstrap] The UNIX system group management has been removed from the
......
debops.bootstrap - Prepare a host for Ansible management
Copyright (C) 2015-2017 Maciej Delmanowski <drybjed@gmail.com>
Copyright (C) 2015-2017 Robin Schneider <ypid@riseup.net>
Copyright (C) 2015-2017 DebOps https://debops.org/
This Ansible role is part of DebOps.
DebOps is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License version 3, as
published by the Free Software Foundation.
DebOps is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with DebOps. If not, see https://www.gnu.org/licenses/.
---
# .. vim: foldmarker=[[[,]]]:foldmethod=marker
# debops.bootstrap default variables [[[
# ======================================
# .. contents:: Sections
# :local:
#
# .. include:: ../../../includes/global.rst
# APT and packages [[[
# --------------------
# .. envvar:: bootstrap__base_packages [[[
#
# Base packages installed during bootstrap.
bootstrap__base_packages: []
# ]]]
# .. envvar:: bootstrap__packages [[[
#
# Install additional packages during bootstrap.
bootstrap__packages: []
# ]]]
# ]]]
# System administrator accounts [[[
# ---------------------------------
# .. envvar:: bootstrap__admin [[[
#
# Enable configuration of administrator accounts.
bootstrap__admin: True
# ]]]
# .. envvar:: bootstrap__admin_system [[[
#
# Should the admin accounts be system accounts (UID < 1000) if not specified
# otherwise?
bootstrap__admin_system: True
# ]]]
# .. envvar:: bootstrap__admin_default_users [[[
#
# List of default user accounts created by the role. See
# :ref:`bootstrap__ref_admin_users` for more details.
bootstrap__admin_default_users:
- name: '{{ ansible_user
if (ansible_user | d() and
ansible_user != "root")
else lookup("env", "USER") }}'
# ]]]
# .. envvar:: bootstrap__admin_users [[[
#
# List of additional user accounts created by the role. See
# :ref:`bootstrap__ref_admin_users` for more details.
bootstrap__admin_users: []
# ]]]
# .. envvar:: bootstrap__admin_groups [[[
#
# List of local system groups which admin accounts will be added to. If any
# groups don't exists, they will be automatically created as "system" groups
# with GID < 1000.
#
# The first specified group is used as the :command:`sudo` passwordless admin group.
#
# All new user accounts will have their home directories in the first group
# listed here as well, to allow easier communication between administrators.
bootstrap__admin_groups: '{{ ansible_local.system_groups.access.root
if (ansible_local|d() and ansible_local.system_groups|d() and
ansible_local.system_groups.access|d() and
ansible_local.system_groups.access.root|d())
else [ "admins" ] }}'
# ]]]
# .. envvar:: bootstrap__admin_home_path [[[
#
# Root path of the home directory of the admin accounts, when they are "normal"
# user accounts with UID and GID >= 1000.
bootstrap__admin_home_path: '/home'
# ]]]
# .. envvar:: bootstrap__admin_home_path_system [[[
#
# Root path of the home directory of the admin accounts, when they are "system"
# user accounts with UID and GID < 1000.
bootstrap__admin_home_path_system: '/var/local'
# ]]]
# .. envvar:: bootstrap__admin_home_group [[[
#
# New admin accounts will have their home directories in this system group to
# allow easier data exchange between system administrators.
bootstrap__admin_home_group: '{{ bootstrap__admin_groups[0] }}'
# ]]]
# .. envvar:: bootstrap__admin_home_mode [[[
#
# Specify permissions for new admin account home directories.
bootstrap__admin_home_mode: '0750'
# ]]]
# .. envvar:: bootstrap__admin_comment [[[
#
# Default comment / GECOS field which is set on the new admin accounts if none
# is specified.
bootstrap__admin_comment: 'System Administrator'
# ]]]
# .. envvar:: bootstrap__admin_shell [[[
#
# Default shell set on the new admin accounts if none is specified.
bootstrap__admin_shell: '/bin/bash'
# ]]]
# .. envvar:: bootstrap__admin_sshkeys [[[
#
# List of SSH keys configured on root and administrator accounts. It takes all
# active keys from your current ssh agent session plus all public keys which you
# keep in the :file:`~/.ssh/` directory of the user which you are bootstrapping DebOps
# from. If you are not happy with that scenario, for example you have some keys
# which you don't like to be included, please modify the variable accordingly
# to your requirements.
bootstrap__admin_sshkeys: [ '{{ lookup("pipe","ssh-add -L | grep ^ssh || cat ~/.ssh/*.pub || true") }}' ]
# ]]]
# ]]]
# ]]]
---
dependencies: []
galaxy_info:
role_name: 'bootstrap'
company: 'DebOps'
author: 'Maciej Delmanowski, Robin Schneider'
description: 'Prepare a host for Ansible management'
license: 'GPL-3.0'
min_ansible_version: '2.0.0'
platforms:
- name: Debian
versions:
- wheezy
- jessie
- name: Ubuntu
versions:
- precise
- quantal
- raring
- saucy
- trusty
galaxy_tags:
- system
- bootstrapping
- bootstrap
---
- name: Gather information about existing home directories
stat:
path: '{{ item }}'
with_items: '{{ lookup("template", "lookup/stat_home_path.j2") | from_yaml }}'
register: bootstrap__register_home
- name: Create admin accounts
user:
name: '{{ item.name }}'
state: 'present'
system: '{{ (item.system | d(bootstrap__admin_system)) | bool }}'
groups: '{{ (item.groups | d(bootstrap__admin_groups)) | join(",") }}'
append: True
comment: '{{ item.comment | d(getent_passwd[item.name][3]
if getent_passwd[item.name]|d()
else bootstrap__admin_comment) }}'
home: '{{ item.home | d(getent_passwd[item.name][4]
if getent_passwd[item.name]|d()
else (((item.system | d(bootstrap__admin_system))
| ternary(bootstrap__admin_home_path_system, bootstrap__admin_home_path)) +
"/" + item.name)) }}'
shell: '{{ item.shell | d(getent_passwd[item.name][5]
if getent_passwd[item.name]|d()
else bootstrap__admin_shell) }}'
with_items: '{{ bootstrap__admin_default_users + bootstrap__admin_users }}'
when: item.name|d()
- name: Set admin home directory group and permissions
file:
path: '{{ item.0.home | d(getent_passwd[item.0.name][4] if getent_passwd[item.0.name]|d() else
(((item.0.system | d(bootstrap__admin_system))
| ternary(bootstrap__admin_home_path_system, bootstrap__admin_home_path)) +
"/" + item.0.name)) }}'
group: '{{ item.0.home_group | d(item.1.stat.gr_name
if item.1.stat.exists|bool
else bootstrap__admin_home_group) }}'
mode: '{{ item.0.home_mode | d(item.1.stat.mode if item.1.stat.exists|bool else bootstrap__admin_home_mode) }}'
with_together:
- '{{ bootstrap__admin_default_users + bootstrap__admin_users }}'
- '{{ bootstrap__register_home.results }}'
when: item.0.name|d()
- name: Install ssh public key on admin accounts
authorized_key:
user: '{{ item.name }}'
key: "{{ (item.sshkeys|d([]) + bootstrap__admin_sshkeys) | join('\n') | string }}"
state: 'present'
with_items: '{{ [{"name": "root"}] + bootstrap__admin_default_users + bootstrap__admin_users }}'
when: item.name|d() and (item.sshkeys|d() or bootstrap__admin_sshkeys)
---
# vim: foldmarker=[[[,]]]:foldmethod=marker
# Package install of essential software [[[
- name: Make sure essential software is installed
package:
name: '{{ item }}'
state: 'present'
tags: [ 'role::bootstrap:packages' ]
with_flattened:
- '{{ bootstrap__base_packages }}'
- '{{ bootstrap__packages }}'
register: bootstrap__register_packages
until: bootstrap__register_packages is succeeded
# ]]]
- name: Gather information about existing users
getent:
database: 'passwd'
split: ':'
tags: [ 'role::bootstrap:admin' ]
- name: Manage System Administrator accounts
import_tasks: admin_accounts.yml
when: bootstrap__admin|bool
tags: [ 'role::bootstrap:admin' ]
{% set output = [] %}
{% if getent_passwd|d() %}
{% for user in (bootstrap__admin_default_users + bootstrap__admin_users) %}
{% if user.name|d() %}
{% if getent_passwd[user.name]|d() %}
{% set _ = output.append(getent_passwd[user.name][4]) %}
{% else %}
{% set _ = output.append(user.home | d(((user.system | d(bootstrap__admin_system)) | ternary(bootstrap__admin_home_path_system, bootstrap__admin_home_path)) + user.name)) %}
{% endif %}
{% else %}
{% set _ = output.append('X') %}
{% endif %}
{% endfor %}
{% endif %}
{{ output | to_nice_yaml }}
......@@ -154,7 +154,6 @@ other hosts.
Host provisioning
-----------------
- :ref:`debops.bootstrap`
- :ref:`debops.grub`
- :ref:`debops.ipxe`
- :ref:`debops.preseed`
......
Copyright
=========
.. literalinclude:: ../../../../ansible/roles/debops.bootstrap/COPYRIGHT
Default variable details
========================
Some of ``debops.bootstrap`` default variables have more extensive
configuration than simple strings or lists, here you can find documentation and
examples for them.
.. contents::
:local:
:depth: 1
.. _bootstrap__ref_admin_users:
bootstrap__admin_users
----------------------
The :envvar:`bootstrap__admin_default_users` and :envvar:`bootstrap__admin_users` lists
specify what admin accounts will be created by the ``debops.bootstrap`` role.
Most of the existing user accounts attributes will not be modified, unless
specific parameters are explicitly set in an user entry.
New and existing user accounts will be added to the system groups specified in
the :envvar:`bootstrap__admin_groups` list. If SSH public keys are set, they will be
added to user accounts as well.
Each entry is a YAML dictionary with specific parameters:
``name``
Required. Name of the user account to create/manage.
``system``
Optional, boolean. If specified and ``True``, new user accounts will be
created as "system" accounts with UID/GID < 1000. If ``False``, new user
accounts will be "normal" user accounts with UID/GID >= 1000. Existing user
accounts are not modified.
If this parameter is not set, :envvar:`bootstrap__admin_system` takes precedence.
``groups``
Optional. List of system groups which a given user account should belong to.
If this parameter is not set, :envvar:`bootstrap__admin_groups` takes precedence.
``comment``
Optional. A comment or GECOS field set for a particular user. If it's not
specified, the current GECOS field will be preserved on existing accounts. On
new user accounts, :envvar:`bootstrap__admin_comment` variable will be set.
``home``
Optional. Home directory path of a given user account. If it's not set, the
current ``$HOME`` directory of an existing user account will be preserved. On
new user accounts, the home directory depends on the account status:
- if it's a "normal" account, its home directory will be located in :file:`/home`
and named after the user account name.
- if it's a "system" account, its home directory will be located in
:file:`/var/local` and named after the user account name.
``shell``
Optional. The default shell executed on login. If not specified, the current
shell will be preserved on existing user accounts. On new accounts,
:envvar:`bootstrap__admin_shell` variable takes precedence.
``home_group``
Optional. If set, the home directory group of a given user account will be
set to this group. If not set, home directories of existing accounts won't be
modified. New accounts will have their home directory group set to the value
of :envvar:`bootstrap__admin_home_group` variable.
``home_mode``
Optional. If set, the home directory of a given user account will have the
specified permissions. If not set, the home directories of existing user
accounts won't be modified. New accounts will have their home directories
permissions set based on the :envvar:`bootstrap__admin_home_mode` variable.
``sshkeys``
Optional. List of SSH public keys to set on an account. This list will be
combined with list of keys set in :envvar:`bootstrap__admin_sshkeys` variable.
Examples
~~~~~~~~
Create two user accounts with default settings, one of which is created only on
Ubuntu hosts:
.. code-block:: yaml
bootstrap__admin_users:
- name: 'ansible'
- '{{ {"name": "ubuntu"}
if ansible_distribution == "Ubuntu"
else {} }}'
Getting started
===============
.. contents::
:local:
Example inventory
-----------------
A host needs to be added to Ansible inventory to allow it to be bootstrapped.
The default DebOps :file:`bootstrap.yml` playbook expects the hosts to be in the
``[debops_all_hosts]`` Ansible group:
.. code-block:: none
[debops_all_hosts]
hostname ansible_ssh_host=hostname.example.com
You might want to set the default DNS domain used by your hosts. To do that,
set the variable below in :file:`ansible/inventory/group_vars/all/netbase.yml` or
in a similar place in inventory:
.. code-block:: yaml
netbase__domain: 'example.com'
In this case, ``debops.netbase`` role included in the bootstrap playbook will
configure the hosts so that their Fully Qualified Domain Name will be, for
example, ``hostname.example.com`` - each host will be placed on a subdomain
inside the ``example.com`` domain.
You can also set the domain through the inventory directly, by setting it in
the host's label in the inventory:
.. code-block:: none
[debops_all_hosts]
hostname.example.com
Example playbook
----------------
Here's an example playbook which uses the ``debops.bootstrap`` role:
.. literalinclude:: ../../../../ansible/playbooks/bootstrap.yml
:language: yaml
How to bootstrap a host with DebOps
-----------------------------------
Within main DebOps playbooks, ``bootstrap`` is a separate playbook which is not
run by default by main playbook. To use it with a new host which has only
a ``root`` account and requires a password, you can run the playbook like this:
.. code-block:: console
user@host:~$ debops bootstrap --limit host --user root --ask-pass
Bootstrap playbook does not have specific host restrictions, so it will be
executed on all hosts (apart from ``localhost``) if not limited, which you
should avoid as done in the example using ``--limit host``.
Ansible tags
------------
You can use Ansible ``--tags`` or ``--skip-tags`` parameters to limit what
tasks are performed during Ansible run. This can be used after a host was first
configured to speed up playbook execution, when you are sure that most of the
configuration is already in the desired state.
Available role tags:
``role::bootstrap``
Main role tag, should be used in the playbook to execute all of the role
tasks as well as role dependencies.
``role::bootstrap:packages``
Execute tasks related to package installation.
``role::bootstrap:admin``
Execute tasks related to setting up the admin user.
``role::bootstrap:hostname``
Execute tasks related to configuring the hostname.
.. _debops.bootstrap:
debops.bootstrap
================
.. toctree::
:maxdepth: 2
introduction
getting-started
defaults
defaults-detailed
copyright
..
Local Variables:
mode: rst
ispell-local-dictionary: "american"
End:
Introduction
============
``debops.bootstrap`` is an Ansible role that helps prepare a given
Debian/Ubuntu host to be managed by Ansible. It will install required packages,
configure hostname and domain, create an admin account and set up SSH public
keys for passwordless SSH access.
Installation
~~~~~~~~~~~~
This role requires at least Ansible ``v2.0.0``. To install it, run:
.. code-block:: console
ansible-galaxy install debops.bootstrap
..
Local Variables:
mode: rst
ispell-local-dictionary: "american"
End:
......@@ -50,7 +50,7 @@ access to the environment variables of the unprivileged account Ansible is
connecting through and can read the ``$SSH_CLIENT`` environment variable and
get the IP address.
Note: Hosts provisioned by the :ref:`debops.bootstrap` role have a workaround in
Note: Hosts provisioned by the ``bootstrap`` playbook have a workaround in
place so that the playbook could be run in privileged mode but to avoid
problems with `other provisioning methods <https://github.com/debops/ansible-core/issues/6#issuecomment-141923939>`_
the role should be run in unprivileged mode as mentioned.
......
......@@ -41,8 +41,6 @@ playbook; you don't need to add hosts to any Ansible groups to enable it.
Example playbook
----------------
Here's an example playbook which uses the ``debops.bootstrap`` role:
If you are using this role without DebOps, here's an example Ansible playbook
that uses the ``debops.machine`` role:
......
......@@ -641,7 +641,6 @@
.. _debops.authorized_keys: https://github.com/debops/ansible-authorized_keys
.. _debops.avahi: https://github.com/debops/ansible-avahi
.. _debops.backporter: https://github.com/debops/ansible-backporter
.. _debops.bootstrap: https://github.com/debops/ansible-bootstrap
.. _debops.boxbackup: https://github.com/debops/ansible-boxbackup
.. _debops.console: https://github.com/debops/ansible-console
.. _debops.core: https://github.com/debops/ansible-core
......@@ -758,7 +757,6 @@
.. _debops.atd documentation: https://docs.debops.org/en/latest/ansible/roles/ansible-atd/docs/index.html
.. _debops.authorized_keys documentation: https://docs.debops.org/en/latest/ansible/roles/ansible-authorized_keys/docs/index.html
.. _debops.avahi documentation: https://docs.debops.org/en/latest/ansible/roles/ansible-avahi/docs/index.html
.. _debops.bootstrap documentation: https://docs.debops.org/en/latest/ansible/roles/ansible-bootstrap/docs/index.html
.. _debops.core documentation: https://docs.debops.org/en/latest/ansible/roles/ansible-core/docs/index.html
.. _debops.cron documentation: https://docs.debops.org/en/latest/ansible/roles/ansible-cron/docs/index.html
.. _debops.cryptsetup documentation: https://docs.debops.org/en/latest/ansible/roles/ansible-cryptsetup/docs/index.html
......
......@@ -306,7 +306,7 @@ Inventory variable changes
You can use the :ref:`debops.ifupdown` role to configure packet forwarding
per network interface, in the firewall as well as via the kernel parameters.
- Host and domain management has been removed from the :ref:`debops.bootstrap`
- Host and domain management has been removed from the ``debops.bootstrap``
role. This functionality is now done via the :ref:`debops.netbase` role,
included in the bootstrap playbook. Some of the old variables have their new
equivalents:
......@@ -466,11 +466,11 @@ Inventory variable changes
enabled automatically.
- The ``bootstrap__sudo`` and ``bootstrap__sudo_group`` variables have been
removed from the :ref:`debops.bootstrap` role. The ``bootstrap.yml`` playbook
removed from the ``debops.bootstrap`` role. The ``bootstrap.yml`` playbook
now uses the :ref:`debops.sudo` role to configure :command:`sudo` service on
a host, use its variables instead to control the service in question.
- The :envvar:`bootstrap__admin_groups` variable will now use list of UNIX
- The ``bootstrap__admin_groups`` variable will now use list of UNIX
groups with ``root`` access defined by the :ref:`debops.system_groups` via
Ansible local facts.
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment