\chapter{Proof of Concept}

Op basis van het technisch ontwerp is een Proof of Concept (POC) gemaakt op basis van de ontworpen oplossing. Dit ontwerp is gebaseerd op de criteria die zijn vastgesteld in het onderzoek. het Proof of Concept moet bevestigen dat het ontwerp functioneert en dat de ontworpen oplossing ook daadwerkelijk toepasselijk is voor de gebruiker (reflectie op de criteria).

Het Proof of Concept is openbaar toegankelijk op \url{https://git.remmen.net/Thesis/kembit.topdesk}.


\section{Ansible Collection}

De plugin is ontwikkeld in een Ansible Collection. Een Ansible Collection is een verzameling van plugins die samen een grote groep van functionaliteiten voorzien. Deze Collection is ontwikkeld om in ieder geval één enkele plugin te bevatten, namelijk de Asset Management inventory plugin. Maar zou in de toekomst uitgebreid kunnen worden met meerdere plugins en modules om een groot aantal functionaliteiten te bieden. \cite{ansible_collection}

Een voordeel van het gebruik van een Ansible Collection is dat deze gemakkelijk te installeren en (dus) te gebruiken is in andere projecten \cite{ansible_collection}.


\section{Koppeling met Asset Management}

Voor de koppeling met Asset Management wordt gebruik gemaakt van de REST API van het Asset Management systeem. In de plugin wordt gebruik gemaakt van Requests, een Python library om HTTP requests te doen \cite{requests}. Deze library biedt een overzichtelijke en gebruikersvriendelijke API om HTTP requests te doen.

In figuur \ref{fig:sequence_diagram} is een sequencediagram gedefinieerd die de communicatie tussen de plugin en Asset Management beschrijft.

\begin{figure}[h]
    \label{fig:sequence_diagram}
    \centering
    \includegraphics[scale=0.7]{figures/integratie_sequentiediagram.pdf}
    \caption{Sequencediagram Ansible Plugin en TOPdesk Asset Management}
\end{figure}

\section{Folderstructuur}

Om als een Ansible Collection gebruikt te kunnen worden, moet deze een bepaalde folderstructuur en bestanden hebben. Deze folderstructuur is hieronder weergegeven.

\begin{lstlisting}[style=tree]
.
├── ansible.cfg
├── galaxy.yml
├── inventory.yaml
├── playbook.yaml
├── plugins
│   └── inventory
│       └── topdesk_am.py
├── README.md
└── requirements.txt
\end{lstlisting}

Een van de benodigde bestanden is het galaxy.yaml bestand. Hierin staat informatie over de Ansible Collection beschreven. Deze is hieronder te zien.

\begin{lstlisting}[caption={galaxy.yaml}]
    namespace: kembit
    name: topdesk
    version: 1.0.0
    readme: README.md
    authors:
    - Martijn Remmen <mremmen@kembit.nl>
    description: Een Ansible collectie voor het integreren met TOPDesk
    license:
    - GPL-2.0-or-later
    license_file: ''
    tags: []
    dependencies: {}
    repository: https://git.remmen.net/Thesis/kembit.topdesk
    documentation: https://git.remmen.net/Thesis/kembit.topdesk/src/branch/master/README.md
    homepage: https://git.remmen.net/Thesis/kembit.topdesk
    issues: https://git.remmen.net/Thesis/kembit.topdesk/issues
    build_ignore: []
\end{lstlisting}


\section{Installatie}

Om de Ansible Collection te installeren moet deze worden opgenomen in een \lstinline{requirements.yaml} bestand in het project. Vervolgens kan met het commando \lstinline{ansible-galaxy install -r requirements.yaml} de Collection worden geïnstalleerd.

De inhoud van de \lstinline{requirements.yaml} bestand is hieronder weergegeven.

\begin{lstlisting}
collections:
- name: https://git.remmen.net/Thesis/kembit.topdesk
    version: v1.0
    type: git
\end{lstlisting}


\section{Gebruik}

Wanneer de plugin geïnstalleerd is kan deze gebruikt worden bij het maken van een Ansible Inventory. Om een Ansible Inventory te maken moet de plugin worden opgenomen in een \lstinline{inventory.yaml} bestand, door dit bovenaan de configuratie te plaatsen. Configuraties voor de plugin kunnen vervolgens in hetzelfde bestand worden gezet.

Het inventory die wordt geproduceerd door de plugin kan worden ingezien door het commando \lstinline{ansible-inventory -i inventory.yaml --list} uit te voeren.

\begin{enumerate}
    \item Zorg ervoor dat Ansible geïnstalleerd is.
    \item Maak een nieuwe folder (of ga naar een bestaand Ansible project)
    \item Maak een nieuw \lstinline{requirements.yaml} bestand aan met de volgende inhoud:
    \begin{lstlisting}
    collections:
    - name: https://git.remmen.net/Thesis/kembit.topdesk
        version: v1.0
        type: git
    \end{lstlisting}
    \item Voer het commando \lstinline{ansible-galaxy install -r requirements.yaml} uit om de Collection te installeren.
    \item Nu kan gebruik worden gemaakt van de kembit.topdesk.topdesk\_am inventory plugin.
\end{enumerate}

\begin{listing}
    \begin{lstlisting}
        plugin: kembit.topdesk.topdesk_am

        url: <url van de TOPdesk installatie (zonder slash op het einde)>
        username: <gebruikersnaam (met rechten tot asset management)>
        application_key: <een applicatie key (zie https://developers.topdesk.com/tutorial.html)>
        
        fields:
          - name
          - type
          - merk
          - serienummer
          - lokaal-ipadres
          - status
          - beheer-ipadres
          - contract
        
        names:
          - KMB-SW300
          - KMB-SW191
          - KMB-SW318
        
        ansible_host: beheer-ipadres        
    \end{lstlisting}
    \caption{Een voorbeeld van een \lstinline{inventory.yaml} bestand die gebruik maakt van de kembit.topdesk.topdesk\_am plugin}
\end{listing}

Het inventory bestand kan worden ingezien door het commando \lstinline{ansible-inventory -i inventory.yaml --list} uit te voeren. Dit commando geeft een overzicht van de assets in het inventory. Hieronder is de output van het commando weergegeven.

\begin{listing}
    \begin{lstlisting}
        {
            "_meta": {
                "hostvars": {
                    "KMB-SW191": {
                        "ansible_host": "1.1.1.1",
                        "beheer-ipadres": "1.1.1.1",
                        "contract": "Ja",
                        "lokaal-ipadres": 10.0.0.10,
                        "merk": "Cisco",
                        "serienummer": "XXXXXXXXX",
                        "status": "Operationeel",
                        "type": "Switch 24 Poorten"
                    },
                    "KMB-SW300": {
                        "ansible_host": "2.2.2.2",
                        "beheer-ipadres": "2.2.2.2",
                        "contract": "Ja",
                        "lokaal-ipadres": 10.0.0.1,
                        "merk": "Cisco",
                        "serienummer": "XXXXXXXXX",
                        "status": "Operationeel",
                        "type": "Switch 48 Poorten"
                    },
                    "KMB-SW318": {
                        "ansible_host": "3.3.3.3",
                        "beheer-ipadres": "3.3.3.3",
                        "contract": "Ja",
                        "lokaal-ipadres": 10.0.0.2,
                        "merk": "Cisco",
                        "serienummer": "XXXXXXXXX",
                        "status": "Operationeel",
                        "type": "Switch 24 Poorten"
                    }
                }
            },
            "all": {
                "children": [
                    "ungrouped"
                ]
            },
            "ungrouped": {
                "hosts": [
                    "KMB-SW191",
                    "KMB-SW300",
                    "KMB-SW318"
                ]
            }
        }
    \end{lstlisting}
    \caption{Een voorbeeld van de output van het commando \lstinline{ansible-inventory -i inventory.yaml --list} (verschillende informatie is weggehaald of aangepast)}
\end{listing}