aim-web2.1.0rc9
This commit is contained in:
admin_rb
@@ -0,0 +1,484 @@
|
||||
# AIM Fresh Installation
|
||||
|
||||
**Applies to:** AIM 3.3.0rc8\
|
||||
**Canonical Ansible Core:** 2.19.11\
|
||||
**Default controller root:** `/etc/ansible`\
|
||||
**Supported AIM Python:** Python 3.11+
|
||||
|
||||
This guide is for a new AIM controller with no existing AIM source tree.
|
||||
It installs the complete source bundle, AIM's Python runtime
|
||||
dependencies, the separate canonical Ansible runtime, and the required
|
||||
Ansible collections.
|
||||
|
||||
The AIM deployer deliberately does **not** install operating-system
|
||||
packages, Python dependencies, Ansible, collections, accounts, groups,
|
||||
services, or add-on executors. Provision those explicitly, then use the
|
||||
bundled deployer in `install` mode.
|
||||
|
||||
AIM remains usable as a standalone product through the built-in `aim`
|
||||
terminal. Add-on execution is optional and disabled by default.
|
||||
|
||||
## 1. Obtain and verify the release
|
||||
|
||||
Transfer both files through a trusted channel:
|
||||
|
||||
``` text
|
||||
AIM-Ansible-3.3.0rc8.zip
|
||||
AIM-Ansible-3.3.0rc8.zip.sha256
|
||||
```
|
||||
|
||||
The SHA-256 sidecar verifies file integrity; it is not a publisher
|
||||
signature.
|
||||
|
||||
Stage the release outside `/etc/ansible`:
|
||||
|
||||
``` bash
|
||||
cd /var/tmp
|
||||
sha256sum -c AIM-Ansible-3.3.0rc8.zip.sha256
|
||||
unzip AIM-Ansible-3.3.0rc8.zip
|
||||
cd aim-core-3.3.0rc8
|
||||
```
|
||||
|
||||
Do not extract the release directly over `/etc/ansible`.
|
||||
|
||||
## 2. Provision the controller prerequisites
|
||||
|
||||
The controller needs:
|
||||
|
||||
- Linux
|
||||
- Python 3.11 or newer for AIM
|
||||
- a separate Ansible runtime containing exactly
|
||||
`ansible-core==2.19.11`
|
||||
- the collections declared by `requirements.yml`
|
||||
- an operator-approved execution/service account and group policy
|
||||
- network and remote authentication prerequisites appropriate to the
|
||||
managed systems
|
||||
|
||||
For the default configuration shipped in this release, review
|
||||
`scripts/aim.yml` before installation. In particular, these values are
|
||||
environment-specific and must not be accepted blindly:
|
||||
|
||||
``` yaml
|
||||
root_dir: /etc/ansible
|
||||
service_user: svc_bf-ansible
|
||||
required_group: srv_debsansible01_admins@bitformer.lan
|
||||
```
|
||||
|
||||
Set them to the intended controller values after installation, or
|
||||
prepare a reviewed configuration before first operational use.
|
||||
|
||||
## 3. Create the AIM Python environment
|
||||
|
||||
Keep AIM's Python environment separate from the canonical Ansible
|
||||
runtime and from add-on environments.
|
||||
|
||||
Example:
|
||||
|
||||
``` bash
|
||||
sudo python3.11 -m venv /opt/aim/venv
|
||||
sudo /opt/aim/venv/bin/python -m pip install --upgrade pip
|
||||
sudo /opt/aim/venv/bin/python -m pip install \
|
||||
'ruamel.yaml>=0.18,<0.19' \
|
||||
'rich>=13,<15'
|
||||
```
|
||||
|
||||
Verify it:
|
||||
|
||||
``` bash
|
||||
/opt/aim/venv/bin/python --version
|
||||
/opt/aim/venv/bin/python -c 'import ruamel.yaml, rich; print("AIM dependencies OK")'
|
||||
```
|
||||
|
||||
The deployer uses this interpreter for the `aim` and `aimctl` launchers.
|
||||
It does not install or upgrade these dependencies itself.
|
||||
|
||||
## 4. Create the canonical Ansible runtime
|
||||
|
||||
AIM 3.3.0rc8 is qualified against **ansible-core 2.19.11**.
|
||||
|
||||
One clean layout is a separate virtual environment:
|
||||
|
||||
``` bash
|
||||
sudo python3.11 -m venv /opt/ansible/venv
|
||||
sudo /opt/ansible/venv/bin/python -m pip install --upgrade pip
|
||||
sudo /opt/ansible/venv/bin/python -m pip install 'ansible-core==2.19.11'
|
||||
```
|
||||
|
||||
Verify the exact version:
|
||||
|
||||
``` bash
|
||||
/opt/ansible/venv/bin/ansible-playbook --version
|
||||
```
|
||||
|
||||
The first version line must report Ansible Core 2.19.11.
|
||||
|
||||
Do not silently substitute a newer Ansible Core release.
|
||||
|
||||
## 5. Install the required Ansible collections
|
||||
|
||||
The source bundle declares:
|
||||
|
||||
``` yaml
|
||||
collections:
|
||||
- ansible.netcommon
|
||||
- name: ansible.windows
|
||||
version: ">=3.8.0,<4.0.0"
|
||||
- ansible.posix
|
||||
- community.windows
|
||||
- community.general
|
||||
- sophos.sophos_firewall
|
||||
- pfsensible.core
|
||||
```
|
||||
|
||||
Install them with the canonical Ansible runtime:
|
||||
|
||||
``` bash
|
||||
sudo /opt/ansible/venv/bin/ansible-galaxy collection install \
|
||||
-r requirements.yml
|
||||
```
|
||||
|
||||
AIM 3.3.0rc8 requires `ansible.windows>=3.8.0,<4.0.0` for native reboot-state discovery. Other collection versions remain operator-approved and must be compatible with Ansible Core 2.19.11. AIM does not download or upgrade collections during source deployment.
|
||||
|
||||
Verify collection discovery:
|
||||
|
||||
``` bash
|
||||
/opt/ansible/venv/bin/ansible-galaxy collection list
|
||||
```
|
||||
|
||||
If collections are installed into a nonstandard path, configure
|
||||
`runtime.ansible_collections_path` in `scripts/aim.yml` after
|
||||
installation.
|
||||
|
||||
## 6. Preview the fresh installation
|
||||
|
||||
For a fresh controller use `install`, not `update`.
|
||||
|
||||
The default installation root is `/etc/ansible`, and the default
|
||||
launcher directory for a fresh installation is `/usr/local/bin`.
|
||||
|
||||
Run a dry-run first:
|
||||
|
||||
``` bash
|
||||
sudo python3 deploy/deploy.py install \
|
||||
--aim-python /opt/aim/venv/bin/python \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
Review the complete plan. It should show source installation under
|
||||
`/etc/ansible` and creation of the `aim` and `aimctl` launchers.
|
||||
|
||||
If using a nondefault controller root, provide both an explicit target
|
||||
and a dedicated command directory:
|
||||
|
||||
``` bash
|
||||
sudo python3 deploy/deploy.py install \
|
||||
--target /srv/aim-controller \
|
||||
--bin-dir /usr/local/libexec/aim-controller \
|
||||
--aim-python /opt/aim/venv/bin/python \
|
||||
--dry-run
|
||||
```
|
||||
|
||||
Do not use a production launcher directory for a second development/test
|
||||
installation.
|
||||
|
||||
## 7. Apply the installation
|
||||
|
||||
For a genuinely fresh tree there should be no active AIM jobs, but the
|
||||
deployer still requires explicit acknowledgement that source
|
||||
writers/runners are quiesced:
|
||||
|
||||
``` bash
|
||||
sudo python3 deploy/deploy.py install \
|
||||
--aim-python /opt/aim/venv/bin/python \
|
||||
--apply \
|
||||
--quiesced
|
||||
```
|
||||
|
||||
Then refresh shell command discovery:
|
||||
|
||||
``` bash
|
||||
hash -r
|
||||
command -v aim
|
||||
command -v aimctl
|
||||
aim --version
|
||||
aimctl --version
|
||||
```
|
||||
|
||||
Expected product version:
|
||||
|
||||
``` text
|
||||
3.3.0rc8
|
||||
```
|
||||
|
||||
The deployer verifies the installed launchers and source before
|
||||
reporting success.
|
||||
|
||||
## 8. Configure AIM
|
||||
|
||||
Edit the installed controller configuration:
|
||||
|
||||
``` bash
|
||||
sudoedit /etc/ansible/scripts/aim.yml
|
||||
```
|
||||
|
||||
At minimum review:
|
||||
|
||||
``` yaml
|
||||
root_dir: /etc/ansible
|
||||
service_user: <approved execution account>
|
||||
required_group: <approved local/NSS group>
|
||||
|
||||
runtime:
|
||||
ansible_playbook: /opt/ansible/venv/bin/ansible-playbook
|
||||
ansible_collections_path: ""
|
||||
private_key_owner: ""
|
||||
|
||||
addons:
|
||||
execution_enabled: false
|
||||
```
|
||||
|
||||
Keep `addons.execution_enabled: false` until add-on/service execution
|
||||
has been deliberately provisioned and accepted.
|
||||
|
||||
`runtime.private_key_owner` affects newly generated keys only. It does
|
||||
not switch the execution UID, migrate existing keys, or grant filesystem
|
||||
access.
|
||||
|
||||
Checkmk-specific controller settings under `maintenance.checkmk_agent`
|
||||
should be configured only when that functionality is required.
|
||||
|
||||
## 9. Establish inventories and customer data
|
||||
|
||||
A fresh source installation does not create production inventories,
|
||||
Vault data, SSH keys, customer credentials, or customer-local
|
||||
configuration.
|
||||
|
||||
The standard controller layout is:
|
||||
|
||||
``` text
|
||||
/etc/ansible/
|
||||
├── scripts/
|
||||
│ ├── aim.yml
|
||||
│ └── ...
|
||||
├── playbooks/
|
||||
├── roles/
|
||||
├── inventories/
|
||||
└── requirements.yml
|
||||
```
|
||||
|
||||
Customer inventories, Vault files, keys, and `.aim.yml` files are
|
||||
runtime/operator data and are intentionally absent from the release
|
||||
archive.
|
||||
|
||||
Create or migrate them through the approved AIM/operator workflow. Never
|
||||
copy credentials into the source release or documentation.
|
||||
|
||||
## 10. Verify Core discovery
|
||||
|
||||
Run:
|
||||
|
||||
``` bash
|
||||
aimctl capabilities
|
||||
```
|
||||
|
||||
Confirm that the product/API information is correct and that expected
|
||||
capabilities are advertised.
|
||||
|
||||
Then inspect the installed documentation:
|
||||
|
||||
``` text
|
||||
/etc/ansible/scripts/docs/README.md
|
||||
/etc/ansible/scripts/docs/SANITY.md
|
||||
/etc/ansible/scripts/docs/VALIDATION.md
|
||||
```
|
||||
|
||||
`VALIDATION.md` records release-development evidence. It is not proof
|
||||
that this newly installed controller has passed managed-host acceptance.
|
||||
|
||||
## 11. Verify controller staging
|
||||
|
||||
Before service/add-on execution, check controller-local Ansible staging:
|
||||
|
||||
``` bash
|
||||
aimctl staging-check
|
||||
```
|
||||
|
||||
For a normal interactive/native installation, AIM checks the relevant
|
||||
controller staging paths.
|
||||
|
||||
For a hardened service executor, run this check **inside the actual
|
||||
service sandbox under the real execution identity**. A successful
|
||||
`sudo -u` shell test does not reproduce systemd mount restrictions.
|
||||
|
||||
With native defaults, both of these may matter:
|
||||
|
||||
``` text
|
||||
<process HOME>/.ansible/tmp
|
||||
<execution account passwd/NSS home>/.ansible/tmp
|
||||
```
|
||||
|
||||
If the service uses `ProtectHome=read-only`, retain that hardening and
|
||||
add only the narrow writable exception required for the private staging
|
||||
directory. Do not make the whole home writable, recursively change
|
||||
ownership, or disable service hardening.
|
||||
|
||||
See:
|
||||
|
||||
``` text
|
||||
scripts/docs/EXECUTOR_STAGING.md
|
||||
```
|
||||
|
||||
## 12. Test the built-in terminal first
|
||||
|
||||
AIM is an independent product. Validate the native terminal before
|
||||
introducing an add-on:
|
||||
|
||||
``` bash
|
||||
aim
|
||||
```
|
||||
|
||||
Use a controlled test customer/host and follow `scripts/docs/SANITY.md`.
|
||||
|
||||
Confirm inventory discovery, credentials/Vault handling, target
|
||||
selection, and an approved low-risk playbook before broader production
|
||||
use.
|
||||
|
||||
## 13. Optional add-on/service execution
|
||||
|
||||
Add-on execution is **disabled by default**.
|
||||
|
||||
Only after the controller and executor identity have been accepted
|
||||
should the operator deliberately enable it:
|
||||
|
||||
``` yaml
|
||||
addons:
|
||||
execution_enabled: true
|
||||
|
||||
runtime:
|
||||
ansible_playbook: /opt/ansible/venv/bin/ansible-playbook
|
||||
```
|
||||
|
||||
The public integration boundary is:
|
||||
|
||||
``` text
|
||||
aim.services.v1
|
||||
aimctl
|
||||
```
|
||||
|
||||
Do not have an add-on:
|
||||
|
||||
- import `aim.ui`
|
||||
- parse AIM terminal output
|
||||
- patch Core
|
||||
- rewrite native Ansible commands
|
||||
- read/export private keys
|
||||
- invent its own inventory hierarchy or target outcomes
|
||||
- reconstruct structured operation results from debug/stdout
|
||||
|
||||
The current add-on contracts are documented in:
|
||||
|
||||
``` text
|
||||
scripts/docs/ADDON_API.md
|
||||
scripts/docs/ADDON_SUPPORT.md
|
||||
scripts/docs/OPERATION_RESULTS.md
|
||||
ADDON_AGENTS.md
|
||||
```
|
||||
|
||||
The v1 execution profile is same-UID. Cross-UID execution is not
|
||||
provided by this release.
|
||||
|
||||
## 14. Run the controller acceptance checklist
|
||||
|
||||
Use the current checklist:
|
||||
|
||||
``` text
|
||||
scripts/docs/SANITY.md
|
||||
```
|
||||
|
||||
For 3.3.0rc8, acceptance should include the structured operation-result
|
||||
path in addition to ordinary execution.
|
||||
|
||||
A useful first reporting test is host-role detection. Confirm that the
|
||||
final result exposes the declared structured capability booleans without
|
||||
requiring the client to parse task output.
|
||||
|
||||
Also exercise, as applicable:
|
||||
|
||||
- inventory hierarchy
|
||||
- target outcome summaries
|
||||
- controller staging
|
||||
- summary and detail progress
|
||||
- disk-usage reporting
|
||||
- service recovery reporting
|
||||
- Checkmk reporting
|
||||
- Linux/Windows patch reporting
|
||||
- successful and mixed-result multi-host runs
|
||||
|
||||
Do not promote a release candidate based only on source parsing or local
|
||||
simulated callback tests.
|
||||
|
||||
## 15. Recovery
|
||||
|
||||
Fresh installation still creates protected deployment recovery data. The
|
||||
deployer prints its exact recovery directory under the default:
|
||||
|
||||
``` text
|
||||
/var/backups/aim-core/
|
||||
```
|
||||
|
||||
If installation validation fails, use the same release deployer and
|
||||
printed recovery directory:
|
||||
|
||||
``` bash
|
||||
sudo python3 deploy/deploy.py rollback \
|
||||
--from-backup /var/backups/aim-core/RECOVERY-DIRECTORY \
|
||||
--dry-run
|
||||
|
||||
sudo python3 deploy/deploy.py rollback \
|
||||
--from-backup /var/backups/aim-core/RECOVERY-DIRECTORY \
|
||||
--apply \
|
||||
--quiesced
|
||||
```
|
||||
|
||||
A source rollback does not reverse remote Ansible work, dependency
|
||||
installation, account/group changes, or add-on state.
|
||||
|
||||
## Fresh-install completion checklist
|
||||
|
||||
A fresh controller is not complete merely because `aim --version` works.
|
||||
Before production use confirm:
|
||||
|
||||
- release ZIP checksum verified
|
||||
- AIM Python 3.11+ environment provisioned
|
||||
- AIM Python dependencies installed
|
||||
- canonical Ansible Core 2.19.11 provisioned separately
|
||||
- required Ansible collections installed and discoverable
|
||||
- full source installed with `deploy.py install`
|
||||
- `aim` and `aimctl` resolve to the intended installation
|
||||
- `scripts/aim.yml` reviewed for this controller
|
||||
- approved execution identity/group configured
|
||||
- inventory/Vault/key data established separately
|
||||
- `aimctl capabilities` succeeds
|
||||
- `aimctl staging-check` succeeds in every execution context
|
||||
- built-in terminal workflow accepted
|
||||
- managed-host sanity tests completed
|
||||
- add-on execution remains disabled unless separately provisioned and
|
||||
accepted
|
||||
- recovery location recorded and protected
|
||||
|
||||
## Related documentation
|
||||
|
||||
- existing root `README.md` --- operator-owned and preserved; AIM does not overwrite it
|
||||
- `deploy/README.md` --- deployment and rollback mechanics
|
||||
- `scripts/docs/README.md` --- current documentation index
|
||||
- `scripts/docs/SANITY.md` --- controller acceptance checklist
|
||||
- `scripts/docs/VALIDATION.md` --- release-development evidence and
|
||||
limits
|
||||
- `scripts/docs/EXECUTOR_STAGING.md` --- hardened executor staging
|
||||
requirements
|
||||
- `scripts/docs/ADDON_API.md` --- public add-on API
|
||||
- `scripts/docs/ADDON_SUPPORT.md` --- current add-on support matrix
|
||||
- `scripts/docs/OPERATION_RESULTS.md` --- structured operation-result
|
||||
contract
|
||||
- `scripts/docs/PLAYBOOKS.md` --- catalog/playbook behavior
|
||||
- `scripts/docs/CHECKMK.md` --- Checkmk-specific behavior
|
||||
Reference in New Issue
Block a user