Deployment Plugins

Recommended Workflow

1. Register the Linux or Windows deployment target first.
2. Create the plugin definition and declare only the secret names the adapter needs.
3. Write the Test playbook first and execute it against a registered target.
4. Add the Deploy playbook only after connectivity and prerequisites are proven.
5. Optionally add Verify and Rollback playbooks.
6. Assign the plugin to a managed custom-application certificate and deploy through the normal SSLNexus certificate pipeline.

Secret Names

The Secret names field declares identifiers, not passwords or tokens themselves. Enter comma-separated names such as API_TOKEN, CLIENT_SECRET, KEYSTORE_PASSWORD. SSLNexus then presents a protected value field for each name.

Values are stored separately from YAML under /etc/ssl-nexus/secrets/plugins/<plugin>/ with restricted permissions and are injected into playbook execution as the plugin_secrets dictionary. Existing values are retained when an edit leaves the value blank.

- name: Call application API
  ansible.builtin.uri:
    url: https://127.0.0.1:9443/api/certificate
    headers:
      Authorization: "Bearer {{ plugin_secrets.API_TOKEN }}"

Test Playbook

The Test playbook is intended for connectivity, privilege and prerequisite validation. It receives target, plugin_secrets and ssl_nexus_test_mode: true. It should not install or replace certificate material.

Linux Test

---
- name: Test custom Linux application
  hosts: all
  gather_facts: false
  become: true
  tasks:
    - name: Check service
      ansible.builtin.command: systemctl is-active myapp
      changed_when: false

Windows Test

---
- name: Test custom Windows application
  hosts: all
  gather_facts: false
  tasks:
    - name: Check service
      ansible.windows.win_service_info:
        name: MyApplication
      register: app_service
    - ansible.builtin.assert:
        that: app_service.exists

The target registration determines the Ansible transport: SSH for Linux and WinRM for Windows. Do not use Linux sudo/become semantics in Windows playbooks.

Deployment Variables

Deploy, Verify and Rollback run with the SSLNexus certificate job and receive the protected runtime variables. The most useful are:

Linux Deployment

Linux targets normally connect as the dedicated SSLNexus management user. Use become: true when the adapter must write protected paths or reload privileged services.

---
- name: Deploy certificate to a Linux application
  hosts: all
  gather_facts: false
  become: true
  tasks:
    - name: Create TLS directory
      ansible.builtin.file:
        path: /etc/myapp/tls
        state: directory
        owner: root
        group: root
        mode: "0700"
    - name: Install certificate
      ansible.builtin.copy:
        src: "{{ cert_src }}"
        dest: /etc/myapp/tls/certificate.pem
        owner: root
        group: root
        mode: "0644"
    - name: Install private key
      ansible.builtin.copy:
        src: "{{ key_src }}"
        dest: /etc/myapp/tls/private-key.pem
        owner: root
        group: root
        mode: "0600"
    - name: Reload application
      ansible.builtin.service:
        name: myapp
        state: reloaded

Windows Deployment

Windows targets use the WinRM connection already stored on the deployment target. Use ansible.windows.* modules and Windows paths.

---
- name: Deploy certificate to a Windows application
  hosts: all
  gather_facts: false
  tasks:
    - name: Create TLS directory
      ansible.windows.win_file:
        path: C:\ProgramData\MyApplication\tls
        state: directory
    - name: Copy certificate
      ansible.windows.win_copy:
        src: "{{ cert_src }}"
        dest: C:\ProgramData\MyApplication\tls\certificate.pem
    - name: Copy private key
      ansible.windows.win_copy:
        src: "{{ key_src }}"
        dest: C:\ProgramData\MyApplication\tls\private-key.pem
    - name: Restart application
      ansible.windows.win_service:
        name: MyApplication
        state: restarted

If the application requires PFX/PKCS#12, build or import it explicitly in the custom plugin according to that application's requirements. Custom plugins should not assume first-party adapter PFX behaviour.

Verify And Rollback

verify.yaml runs after a successful deployment. Use it to inspect the installed certificate, query the application or prove service health. A failed verify marks the deployment as failed.

rollback.yaml runs when deployment fails and is also invoked after verification failure. Keep rollback idempotent and safe after a partially completed deployment.

How SSLNexus Stores And Runs The Yaml

SSLNexus writes the supplied files as test.yaml, deploy.yaml, verify.yaml and rollback.yaml beneath the plugin directory. Each supplied playbook is passed through ansible-playbook --syntax-check before the plugin manifest is published. The manifest records the exact playbook names, and runtime execution resolves those files through the same deployment pipeline used by the managed certificate job.

Production deployment never executes arbitrary browser text directly. Deploy runs first, Verify runs only after Deploy succeeds, and Rollback is the failure hook.

Team Source Control

Custom Deployment Plugins can be stored in GitHub, Bitbucket Cloud or GitLab. The organisation configures one approved account/workspace/group per provider, then each SSLNexus administrator connects their own identity for repository access and attribution.

Use Pull into editor to load repository files into this same editor and validation pipeline. Use Publish current plugin to save and validate locally before committing plugin.json and the available YAML playbooks.

Configure GitHub, Bitbucket Or GitLab →