Rationalisation de l'accès aux laboratoires Instruqt intégrés

Wie vermittelt man Interessenten und Kunden ein sehr technisches Thema? Wie sorgt man für eine reibungslose Fahrt?

Bei Isovalent ist es uns ein Anliegen, die Lernerfahrung für unsere Benutzer so reibungslos wie möglich zu gestalten. Isovalent sind die Entwickler von Cilium, der De-facto Cloud-Networking-Plattform für Kubernetes. Obwohl wir Netzwerke und Sicherheit lieben, sind wir uns darüber im Klaren, dass es für manche Menschen ein schwieriges Thema sein könnte. Wir dachten, wir würden das Erlernen von Kubernetes-Netzwerken zum Spaß machen, deshalb legen wir Wert darauf, die Lernerfahrung spielerisch zu gestalten.
Instruqt bietet eine großartige Plattform zum Aufbau praktischer Labore, die sowohl technisch fortgeschritten als auch für Benutzer ansprechend sein können.

Wir glauben außerdem, dass die Benutzererfahrung reibungslos und die Prozesse vollständig automatisiert sein sollten.
Glücklicherweise kann durch die Nutzung der Instruqt graphQL API viel erreicht werden.
Zu diesem Zweck haben wir unsere eigene instruqt-go-Bibliothek geschrieben, die wir als Open Source veröffentlichen möchten. Die Bibliothek soll Entwicklern dabei helfen, die Instruqt-Plattform problemlos zu automatisieren und zu integrieren.

Eines der Probleme bei der Veröffentlichung von Instruqt-Labs besteht darin, Benutzerinformationen von Instruqt mit denen Ihrer eigenen Datenbank oder Ihres CRM zu verknüpfen.
In diesem ersten Beitrag führen wir Sie durch die Erstellung eines Proxys mit instruqt-go that:

• sammelt Benutzerkennungen (z. B. HubSpot-Tokens);
• überprüft die Benutzeridentität;
• leitet Benutzer zu einem Labor mit eindeutigen Zugriffstoken weiter, die über die Instruqt-API generiert werden.

Wir werden die Funktion dann auf Google Cloud Functions veröffentlichen.

Warum ein Proxy

Es gibt verschiedene Gründe, Benutzerinformationen in Laboren zu sammeln:

• Es ist nützlich, nach Abschluss des Labors Abzeichen generieren zu können (und wir lieben Abzeichen) (mehr dazu in einem zukünftigen Beitrag).
• Es ermöglicht Benutzern, ihren Fortschritt in den Laboren anzuzeigen, damit sie wissen, welche sie absolvieren müssen (siehe zum Beispiel die Karte der Cilium-Labore).

So übergeben Sie Benutzerdaten

Es gibt verschiedene Methoden, Benutzerdaten an Instruqt-Tracks zu übergeben.

Benutzerdefinierte Parameter

Benutzerdefinierte Instruqt-Parameter sind sehr nützlich, um beim Starten eines Tracks jegliche Art von Informationen zu übergeben. Diese Felder werden einfach als Abfrageparameter mit dem Präfix icp_ zur URL hinzugefügt. Diese Parameter können auch in Instruqt-Webhooks sowie über die Instruqt GraphQL-API abgerufen werden, wodurch sie praktisch zu verwenden sind.

Bis vor kurzem ermutigte Instruqt Track-Entwickler, Benutzerinformationen (wie Name, E-Mail oder Token) mithilfe benutzerdefinierter Parameter weiterzugeben.

Die Verwendung benutzerdefinierter Parameter hat jedoch einige Nachteile:

1. Sie sind nicht standardisiert und werden von Instruqt nicht interpretiert. Dies bedeutet, dass Benutzersitzungen in Instruqt-Berichten als anonym angezeigt werden (und die eindeutige Benutzeranzahl möglicherweise falsch ist).
2. Sie sind standardmäßig nicht verschlüsselt. Sie können sie natürlich mit Ihren eigenen Schlüsseln verschlüsseln, aber Instruqt zeigt Ihnen den verschlüsselten Wert in Spielberichten an.
3. Ich habe mehrfach gesehen, dass benutzerdefinierte Parameter verloren gingen, wenn Benutzer ein Labor neu starteten. Ich habe tatsächlich meine eigene Cache-Datenbank gestartet, um diesem Problem entgegenzuwirken.

Lädt ein

Mit Instruqt-Einladungen können Sie eine Liste von Titeln erstellen und einen Einladungslink generieren, der für einen einfachen Zugriff mit Benutzern geteilt werden kann. Einladungen können so eingestellt werden, dass Benutzerdaten über ein Formular erfasst werden.

Diese Benutzerdaten werden dann zu den Benutzerdetails auf Instruqt hinzugefügt (Benutzerdetails sind an Benutzerkonten angehängt, aber für jedes Instruqt-Team eindeutig).

Das ist für Werkstätten äußerst praktisch, es gibt aber auch hier ein paar Einschränkungen:

1. Wenn Sie eine Einladung verwenden, um auf alle Labs zuzugreifen, muss die Einladung alle veröffentlichten Labs enthalten.
2. Einladungen haben ihre eigene Zielseite, daher würde es nicht mit unserer Cilium Labs-Karte oder anderen Kiosk-Ansätzen funktionieren.

Hinweis: Instruqt hat kürzlich Landing Pages eingeführt, eine Form von Einladungen mit einer Möglichkeit, die Landing Page zu optimieren, mit denselben Vorteilen und Einschränkungen.

Formulare von Drittanbietern

Kürzlich hat Instruqt eine weitere Möglichkeit zur Weitergabe von Benutzerinformationen hinzugefügt, die die Vorteile beider vorheriger Methoden vereint.

Die verschlüsselte PII-Methode ermöglicht die Übergabe eines pii_tpg-Abfrageparameters an eine Einbettungs-URL. Das bedeutet:

1. Die Daten werden mit einem von Instruqt bereitgestellten öffentlichen Schlüssel verschlüsselt, sodass URLs keine lesbaren Benutzerinformationen enthalten.
2. Instruqt versteht die pii_tpg-Daten und verfügt über den privaten Schlüssel, um sie zu entschlüsseln. Die Informationen werden verwendet, um die Daten des Benutzers einzugeben, so als ob er eine Einladung angenommen hätte.
3. Dies ist nicht mit Einladungen verknüpft, daher kann es mit jedem Track verwendet werden.

Wir werden diese neue Methode in diesem Beispiel verwenden, da sie heute die vielseitigste ist, um Informationen auf sichere und zuverlässige Weise an Instruqt weiterzuleiten.

Nota mengenai Token Benamkan

Apabila anda melawat halaman runut pada Instruqt, terdapat pilihan untuk membenamkan runut.
Ini memberi anda URL yang mengandungi token unik pada runut.

Walaupun sah untuk menggunakan URL itu, ini juga bermakna sesiapa yang mempunyai akses kepada token ini boleh memulakan trek pada bila-bila masa yang mereka mahu.

Instruqt baru-baru ini telah menambah panggilan API untuk menjana token sekali untuk runut, supaya URL yang menggunakan token sedemikian hanya boleh digunakan sekali.

Proksi yang kami kodkan akan menggunakan token sekali sahaja, kerana kami mempunyai akses kepada API dan boleh menjananya dengan mudah.

Mencipta Proksi

Langkah Permulaan

Pertama, buat direktori untuk fungsi anda:

mkdir instruqt-proxy

Alih ke direktori ini dan mulakan persekitaran Go:

# Replace example.com with the prefix of your choice
go mod init example.com/labs

Memanfaatkan Fungsi Awan Google

Untuk ujian tempatan, buat direktori cmd:

mkdir cmd

Buat fail main.go dalam direktori itu, dengan kandungan berikut:

package main

import (
    "log"
    "os"

    // Blank-import the function package so the init() runs
  // Adapt if you replaced example.com earlier
    _ "example.com/labs"

    "github.com/GoogleCloudPlatform/functions-framework-go/funcframework"
)

func main() {
    // Use PORT environment variable, or default to 8080.
    port := "8080"
    if envPort := os.Getenv("PORT"); envPort != "" {
        port = envPort
    }
    if err := funcframework.Start(port); err != nil {
        log.Fatalf("funcframework.Start: %v\n", err)
    }
}

Mencipta Fungsi

Kembali ke direktori instruqt-proxy, buat fail proxy.go dan mulakan dengan menambahkan fungsi init() padanya, bersama-sama dengan pakej Go yang akan kami gunakan:

package labs

import (
    "fmt"
    "net/http"
    "net/url"
    "os"

    "github.com/GoogleCloudPlatform/functions-framework-go/functions"

    "github.com/isovalent/instruqt-go/instruqt"
)

func init() {
    functions.HTTP("InstruqtProxy", instruqtProxy)
}

Ini akan membolehkan Google Cloud Functions memanggil fungsi instruqtProxy apabila ia dimulakan.

Jom tulis fungsi itu:

const (
    // Replace team name with yours
    instruqtTeam = "isovalent"
)

func instruqtProxy(w http.ResponseWriter, r *http.Request) {
    instruqtToken := os.Getenv("INSTRUQT_TOKEN")

    if instruqtToken == "" {
        w.WriteHeader(http.StatusInternalServerError)
        return
    }

    instruqtClient := instruqt.NewClient(instruqtToken, instruqtTeam)

    // Get user from passed token
    utk := r.URL.Query().Get("utk")
    if utk == "" {
        w.WriteHeader(http.StatusUnauthorized)
        return
    }

    user, err := getUser(utk)
    if err != nil {
        w.WriteHeader(http.StatusUnauthorized)
        return
    }

    labSlug := r.URL.Query().Get("slug")

    url, err := getLabURL(instruqtClient, user, labSlug)
    if err != nil {
        w.WriteHeader(http.StatusNotFound)
        return
    }

    http.Redirect(w, r, url, http.StatusFound)
}

Dalam fungsi ini, kami:

1. dapatkan token Instruqt daripada pembolehubah persekitaran INSTRUQT_TOKEN
2. mulakan klien Instruqt API untuk token dan pasukan
3. dapatkan semula parameter utk daripada parameter URL untuk mengesahkan pengguna
4. dapatkan maklumat pengguna berdasarkan UTK itu
5. dapatkan slug makmal daripada parameter URL
6. dapatkan semula URL makmal untuk ubah hala
7. ubah hala pengguna menggunakan fungsi http.Redirect

Laksanakan getLabURL()

Fungsi getLabURL akan menjana URL ubah hala untuk makmal berdasarkan maklumat pengguna, slug makmal yang diminta dan maklumat dinamik daripada Instruqt API.

Jom tulis:

const (
    // Replace with your sign-up page format
    labSignupPage = "https://isovalent.com/labs/%s"

    // Adapt to your values
    finishBtnText = "Try your next Lab!"
    finishBtnURL  = "https://labs-map.isovalent.com/map?lab=%s&showInfo=true"
)

func getLabURL(instruqtClient *instruqt.Client, u user, slug string) (string, error) {
    track, err := instruqtClient.GetTrackBySlug(slug)
    if err != nil {
        return "", err
    }

    // Unknown user
    if u.Email == "" {
        url := fmt.Sprintf(labSignupPage, slug)
        return url, nil
    }

    // Get one-time token
    token, err := instruqtClient.GenerateOneTimePlayToken(track.Id)
    if err != nil {
        return "", err
    }

    labURL, err := url.Parse(fmt.Sprintf("https://play.instruqt.com/embed/%s/tracks/%s", instruqtTeam, track.Slug))
    if err != nil {
        return "", err
    }

    // Prepare the fields to encrypt
    encryptedPII, err := instruqtClient.EncryptUserPII(u.FirstName, u.LastName, u.Email)
    if err != nil {
        return "", err
    }

    // Add params
    params := map[string]string{
        "token":             token,
        "pii_tpg":           encryptedPII,
        "show_challenges":   "true",
        "finish_btn_target": "_blank",
        "finish_btn_text":   finishBtnText,
        "finish_btn_url":    fmt.Sprintf(finishBtnURL, track.Slug),
    }

    q := labURL.Query()
    for key, value := range params {
        q.Set(key, value)
    }

    // Encode the parameters
    labURL.RawQuery = q.Encode()

    return labURL.String(), nil
}

Pertama, ambil perhatian bahawa kami telah menentukan beberapa pemalar baharu yang boleh anda tala:

• labSignupPage ialah URL di tapak web anda di mana pengguna yang tidak disahkan akan diubah hala. Ia mengandungi pembolehubah untuk slug makmal.
• finishBtnText ialah teks yang ditunjukkan pada butang penamat makmal.
• finishBtnURL ialah tindakan butang di hujung makmal. Ia juga mengandungi pembolehubah untuk slug makmal.

Sekarang mari kita terangkan langkah-langkah fungsi getLabURL():

1. Dapatkan maklumat runut daripada Instruqt API, ralat jika tidak ditemui.
2. Jika pengguna tidak dikenali, ubah hala ke halaman pendaftaran.
3. Jana token sekali untuk akses trek terbenam.
4. Jana URL ubah hala.
5. Sulitkan maklumat pengguna menggunakan kekunci PII daripada Instruqt API.
6. Tambah semua parameter (token sekali sahaja, maklumat pengguna yang disulitkan, pilihan butang selesai) pada URL ubah hala.
7. Enkodkan URL.
8. Kembalikan URL yang terhasil.

Fungsi getUser().

Sekeping terakhir yang tiada dalam proksi ini ialah fungsi getUser(). Saya tidak dapat membantu anda banyak di sini, kerana bahagian ini adalah tempat anda memasukkan logik anda sendiri. Anda mungkin menggunakan CRM seperti Hubspot untuk mendapatkan maklumat hubungan daripada UTK atau pangkalan data lain, terpulang kepada anda!

Kod yang saya akan tunjukkan kepada anda di sini hanya mengembalikan contoh pengguna:

/*
 * This is where you add the logic to get user information from your CRM/database.
 */
type user struct {
    FirstName string
    LastName  string
    Email     string
}

func getUser(utk string) (u user, err error) {
    // Implement the logic to get your user information from UTK

    u = user{
        FirstName: "John",
        LastName:  "Doe",
        Email:     "john@doe.com",
    }

    return u, err
}

Menguji kod

Sekarang kita mempunyai keseluruhan fungsi proxy.go, mari kita ujinya!

Mula-mula, kemas kini fail go.mod dan go.sum anda dengan:

go get ./...
go mod tidy

Dalam papan pemuka Instruqt anda, pergi ke "kunci API" dan dapatkan nilai kunci API anda. Eksportnya sebagai pembolehubah dalam shell anda:

export INSTRUQT_TOKEN=<your_instruqt_token>

Seterusnya, lancarkan fungsi pada mesin tempatan anda:

FUNCTION_TARGET=InstruqtProxy go run ./cmd/main.go

Akhir sekali, dalam terminal lain, buat permintaan ujian kepada localhost:8080 di mana fungsi anda akan berjalan (anda boleh lulus pembolehubah persekitaran PORT di atas untuk menukar port jika perlu):

curl  -i "localhost:8080/?slug=cilium-getting-started&utk=someUtkValue"

Suaikan diri untuk menggunakan slug trek yang wujud dalam organisasi Instruqt anda. Jika runut itu wujud, anda seharusnya mendapat respons 302 dengan URL ubah hala yang mengandungi token sekali untuk akses, serta maklumat John Doe yang disulitkan dengan kunci PII dan token sekali (bermula dengan ott_)!

Ujian alternatif: menggunakan Docker

Jika anda ingin menggunakan Docker untuk menguji fungsi anda secara setempat, anda boleh mencipta Dockerfile dalam direktori semasa anda:

FROM golang:1.23

WORKDIR /app

COPY . .

RUN go build -o myapp ./cmd/main.go

ENV DEV=true
ENV PORT=8080

EXPOSE $PORT

CMD ["./myapp"]

Tambahkan fail docker-compose.yaml:

version: '3'
services:
  proxy:
    build: ./
    ports:
      - "8080:8080"
    environment:
      INSTRUQT_TOKEN: ${INSTRUQT_TOKEN}
      FUNCTION_TARGET: InstruqtProxy

Akhir sekali, bina dan lancarkan bekas anda:

docker-compose up --build

Dan anda boleh menghantar permintaan ke localhost:8080 sama seperti sebelumnya!

Hosting the Proxy on Google Cloud Functions

In order to deploy to Google Cloud, first make sure you are logged in to your Google Cloud project:

gcloud auth application-default login

Create a Secret for the API Token

Next, let's create a new secret for the Instruqt token:

echo -n "$INSTRUQT_TOKEN" | gcloud secrets create instruqt-token --data-file=-

In order to adjust the permissions on this secret, you will need to get your project ID:

PROJECT_NUMBER=$(gcloud projects describe $(gcloud config get-value project) --format="value(projectNumber)")

Then, add the "Secret Manager Secret Accessor" role for the default Compute Engine service account for the project:

gcloud secrets add-iam-policy-binding instruqt-token \
    --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
    --role="roles/secretmanager.secretAccessor"

Your secret is now ready to be used by the function!

Deploy the Function

You can then deploy the function (adapt the region if needed):

gcloud functions deploy "instruqt-proxy" \
  --gen2 --runtime=go122 --region=europe-west1 --source=. \
  --entry-point="InstruqtProxy" --trigger-http --allow-unauthenticated \
  --set-secrets="INSTRUQT_TOKEN=instruqt-token:latest"

This will upload and build your project, and return the URL to access the function.

This URL will look something like https://europe-west1-.cloudfunctions.net/instruqt-proxy.
You can then test the function using that URL instead of localhost:8080!

Further Considerations

This is a simplified approach to the lab proxy we use at Isovalent. There are things you might want to consider with this implementation:

• If you have actual user (instead of marketing contact), switch to a proper authentication system (e.g. JWT) instead of UTK.
• The current implementation will give access to any lab in your collection if you know its slug. You might want to filter them out (using for example track tags).
• This implementation manages errors but is very basic in logging. We would recommend using Google Cloud logging to easily audit function runs.
• You might want to pass extra information as custom parameters. For example, we like to pass some form of even or campaign ID. These can then be retrieved via the API as part or the Track structure.
• If you're using a custom form and redirecting to the proxy, you might want to be sure your CRM/database has already gotten the user information. You can for example implement a retry logic in the proxy function.
• Invite embed URLs contain the invite ID. If you want to support invites, the proxy could take an optional invite parameter and add it to the URL.

Using the Proxy

This proxy can typically be used to give access to authenticated users in a safe way, while preserving user information in Instruqt reports and making sure embed URLs are not reusable.

Here is an example of usage of this proxy:

1. Set up lab sign-up pages with the form system of your choice (e.g. using Hubspot forms).
2. Retrieve a user identifier from the page context (e.g. a Hubspot cookie token).
3. Redirect users to the proxy, passing the user identifier and lab slug as parameters.

This can allow you to build a series of public sign-up pages for your labs, similar to what we have built on the Isovalent website. It can also be used to build a Kiosk interface, or even a more creative landing page such as the Cilium Labs map, where clicks on the map redirect to the lab proxy.

By making a complex networking technology like Cilium fun with our labs, we have made it the experience for users less intimidating and more approachable. Using our proxy can help you provide a similar user experience to your prospects. Please get in touch if you have any questions.

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!