Per distribuire l'agente Java APM, effettuare le operazioni riportate di seguito.

1. Prima di continuare, confermare di aver completato i prerequisiti e di aver effettuato il provisioning dell'agente Java APM.
   Nota
   
   Quando si esegue il provisioning dell'agente Java APM, si consiglia di eseguirne il provisioning in qualsiasi posizione del computer locale e di copiarlo in un'immagine Docker.
2. Modificare Dockerfile per copiare l'agente Java APM in un'immagine Docker:

   COPY <DESTINATION_DIRECTORY>/oracle-apm-agent <Docker_Image_Directory>/oracle-apm-agent/

   Si noti che <DESTINATION_DIRECTORY> indica la posizione sul computer locale in cui è stato eseguito il provisioning dell'agente Java APM e <Docker_Image_Directory> indica la directory nell'immagine Docker in cui si sta copiando l'agente Java APM. <Docker_Image_Directory> potrebbe anche essere la directory di destinazione del server applicazioni in Docker, ad esempio $DOMAIN_HOME, se si utilizza Oracle WebLogic Server.

3. Aggiungere la seguente opzione -javaagent allo script di avvio del server applicazioni:

   java -javaagent:<Docker_Image_Directory>/oracle-apm-agent/bootstrap/ApmAgent.jar -jar target/<appserver.jar>

4. Crea una nuova immagine Docker con l'agente Java APM integrato e lo script di avvio modificato, quindi esegui il PUSH dell'immagine nel registro.

Se utilizzi Kubernetes per gestire i container Docker, aggiorna la configurazione Kubernetes in modo che utilizzi la nuova immagine Docker e riavvia il pod Kubernetes.

Inoltre, puoi impostare dimensioni aggiuntive da segnalare dal pod Kubernetes utilizzando l'API verso il basso, copiando le seguenti impostazioni di ambiente e volume nella specifica di distribuzione (file yaml) del pod Kubernetes. Per informazioni sull'API verso il basso, consulta la sezione relativa all'API verso il basso nella documentazione di Kubernetes.

Impostazioni di ambiente

spec:
  containers:
  - name: <container-name>
    image: image: <your-registry>/<your-docker-image>:latest
    env:
      - name: APM_ATTRIBUTES_K8S_POD_NAME
        valueFrom:
          fieldRef:
            fieldPath: metadata.name
      - name: APM_ATTRIBUTES_K8S_NAMESPACE_NAME
        valueFrom:
          fieldRef:
            fieldPath: metadata.namespace
      - name: APM_ATTRIBUTES_K8S_NODE_NAME
        valueFrom:
          fieldRef:
            fieldPath: spec.nodeName

Impostazioni volume

spec:
  containers:
  - name: <container-name>
    image: image: <your-registry>/<your-docker-image>:latest
    volumeMounts:
      - name: apm-attributes-k8s
        mountPath: /etc/apm-attributes-k8s
    volumes:
      - name: apm-attributes-k8s
        downwardAPI:
         items:
           - path: "labels"
             fieldRef:
               fieldPath: metadata.labels
           - path: "annotations"
             fieldRef:
               fieldPath: metadata.annotations

Prerequisito: installare l'operatore OpenTelemetry nel cluster Kubernetes.

Sono disponibili tre diverse opzioni: File manifesto di rilascio dell'operatore, Grafico helm dell'operatore o Hub dell'operatore.

Nella maggior parte dei casi, è necessario installare cert-manager. Se si utilizza l'opzione del grafico helm, è possibile generare un certificato con firma automatica.

kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.14.2/cert-manager.yaml

Per installare l'operatore OpenTelemetry, eseguire le operazioni riportate di seguito.

kubectl apply -f https://github.com/open-telemetry/opentelemetry-operator/releases/latest/download/opentelemetry-operator.yaml

Distribuire l'agente Java APM

Per distribuire l'agente Java APM, effettuare le operazioni riportate di seguito.

1. Crea una risorsa personalizzata (CR) Kubernetes.

   Per gestire la strumentazione automatica, all'operatore OpenTelemetry devono essere fornite informazioni sull'agente Java APM e sulla relativa configurazione che vengono eseguite utilizzando la definizione di risorse personalizzate (CRD).

   Questa risorsa personalizzata verrà utilizzata dall'operatore per copiare l'agente nel pod e aggiungervi la configurazione richiesta.

   Per creare il CR, eseguire le operazioni riportate di seguito.

   kubectl apply -f - <<EOF
   apiVersion: opentelemetry.io/v1alpha1
   kind: Instrumentation
   metadata:
     name: inst-apm-java
     namespace: opentelemetry-operator-system
   spec:
     java:
       image: container-registry.oracle.com/oci_observability_management/oci-apm-java-agent:1.15.0.516
       env:
         - name: OTEL_com_oracle_apm_agent_data_upload_endpoint
           value: <data-upload-endpoint>
         - name: OTEL_com_oracle_apm_agent_private_data_key
           value: <private-data-key>
   EOF

   dove:

   • <data-upload-endpoint> è l'URL dell'endpoint di caricamento dati generato quando viene creato il dominio APM. Per informazioni, vedere Ottenere endpoint di caricamento dati e chiavi dati.
   • <private-data-key> è la chiave dati privata di installazione dell'agente Java APM generata quando viene creato il dominio APM. Per informazioni, vedere Ottenere endpoint di caricamento dati e chiavi dati.
   È possibile eseguire la query sulla CR creata eseguendo il seguente comando:

   kubectl get otelinst -n opentelemetry-operator-system

   Tutti gli endpoint e le variabili di ambiente devono essere corretti affinché la strumentazione automatica funzioni correttamente.
2. Aggiungere l'annotazione Kubernetes.

   L'operatore OpenTelemetry utilizza l'annotazione Kubernetes per decidere quali pod devono essere inseriti automaticamente con l'agente Java APM.

   L'annotazione può essere aggiunta a uno spazio di nomi. In tal caso, tutti i pod all'interno di tale spazio di nomi verranno iniettati. L'annotazione può essere aggiunta anche a singoli oggetti PodSpec, disponibili come parte di Distribuzione, Statefulset e altre risorse.

   Annotazione:

   instrumentation.opentelemetry.io/inject-java: "opentelemetry-operator-system/inst-apm-java"

   Per iniziare a modificare lo spazio di nomi, effettuare le operazioni riportate di seguito.

   • Eseguire il comando:

     kubectl edit namespace <your-namespace-name>

   • Modificare lo spazio di nomi una volta aperto l'editor. ad esempio, l'editor vi.
   • Aggiungere l'annotazione allo spazio di nomi. Tenere presente che il rientro è molto importante per renderlo un file YAML valido.
   Ad esempio:

   apiVersion: v1
   kind: Namespace
   metadata:
     labels:
       kubernetes.io/metadata.name: mynamespace
     annotations:
       instrumentation.opentelemetry.io/inject-java: "opentelemetry-operator-system/inst-apm-java"
     name: mynamespace
   spec:

3. Riavviare il pod Kubernetes.

   Per riavviare il pod in cui si desidera inserire automaticamente l'agente Java APM, eseguire le operazioni riportate di seguito.

   kubectl delete pod <your-pod-name> -n <your-namespace-name>

4. Verificare il pod Kubernetes.
   Per verificare che il pod sia stato inserito automaticamente con l'agente Java APM dopo il riavvio, eseguire le operazioni riportate di seguito.

   kubectl get pod <your-pod-name> -n <your-namespace-name> -o yaml

È ora possibile passare al passo successivo: Verifica distribuzione agente Java APM.

Per distribuire l'agente Java APM su un volume di cui è stato eseguito il MOUNT, attenersi alla procedura riportata di seguito.

1. Confermare di aver completato i task dei prerequisiti dell'agente Java APM.

   Prendere nota dell'endpoint e della chiave dati di caricamento dati al momento della creazione del dominio APM.

2. Crea un nuovo file system che monterà i pod.

   Quando si crea il file system, è importante assicurarsi di selezionare lo stesso compartimento VCN (Virtual Cloud Network) utilizzato da Kubernetes. Eseguire le stesse operazioni per il compartimento della subnet.

3. Installa il file system nei pod.

   Questo passaggio richiede modifiche ai file yaml corrispondenti.

   Creare il file PersistentVolume e le entità correlate in Kubernetes utilizzando il file yaml riportato di seguito. Tenere presenti i seguenti campi da modificare per l'ambiente in uso: mntTargetId, server e path.

   kind: StorageClass
   apiVersion: storage.k8s.io/v1
   metadata:
     name: oci-fss
   provisioner: oracle.com/oci-fss
   parameters:
     mntTargetId: ocid1.mounttarget.oc1.iad.xxxxxxxxxxxxxxxxxxxxxx
   ---
   apiVersion: v1
   kind: PersistentVolume
   metadata:
    name: oke-fsspv
   spec:
    storageClassName: oci-fss
    capacity:
     storage: 10Gi
    accessModes:
     - ReadWriteMany
    mountOptions:
     - nosuid
    nfs:
   # Replace this with the IP of your FSS file system in OCI
     server: 10.0.10.39
   # Replace this with the Path of your FSS file system in OCI
     path: "/fss-for-kub"
     readOnly: false
   ---
   apiVersion: v1
   kind: PersistentVolumeClaim
   metadata:
    name: oke-fsspvc
   spec:
    storageClassName: oci-fss
    accessModes:
    - ReadWriteMany
    resources:
     requests:
    # Although storage is provided here it is not used for FSS file systems
       storage: 10Gi
    volumeName: oke-fsspv

   Per applicare le modifiche, eseguire kubectl apply -f <filename.yaml>

   Quindi, aggiornare il file yaml che gestisce i pod e aggiungere il volume e il MOUNT del volume.

   Per avere effetto, ricreare i pod.

4. Scaricare il file dell'agente Java APM.

   Scaricare e copiare il file nel volume di cui è stato eseguito il MOUNT.

   Per istruzioni sul download, vedere Scaricare il software APM Java Agent.

   Dopo il download, copiarlo nel volume installato.

5. Eseguire il provisioning dell'agente Java APM.

   Eseguire il login a uno dei contenitori per eseguire il provisioning dell'agente Java APM, individuare il file jar apm-java-agent-installer ed eseguire le operazioni riportate di seguito.

   java -jar ./apm-java-agent-installer-<version>.jar provision-agent -service-name=<Name of the Service> -destination=<Destination_Directory> -private-data-key=<Agent installation key generated during APM domain creation> -data-upload-endpoint=<dataUploadEndpoint URL generated during APM domain creation>

   Per istruzioni sul provisioning, vedere Eseguire il provisioning dell'agente Java APM.

6. Distribuire l'agente Java APM.

   Distribuire l'agente Java APM fornendo la posizione oracle-apm-agent al microservizio nel file yaml.

   Aggiungere l'argomento -javaagent e la posizione del file jar dell'agente APM al comando java di ogni microservizio:

   java -javaagent:<Mounted Volume>/oracle-apm-agent/bootstrap/ApmAgent.jar

7. Riavviare Kubernetes.

   Ricreare i pod eseguendo: kubectl apply -f <filename.yaml>.

   È ora possibile passare al passo successivo: Verifica distribuzione agente Java APM.