Accéder à sa base de données

Vos bases de données PostgreSQL sont gérées par CloudNativePG (CNPG — voir PostgreSQL managé pour en créer une) et ne sont pas exposées publiquement par défaut. Pour vous y connecter depuis votre poste, vous devez utiliser un port-forward — soit en ligne de commande avec kubectl, soit via l’interface graphique de Freelens.

Astuce

Cette procédure nécessite d’avoir récupéré votre kubeconfig au préalable.

Prérequis

Choisir un client au choix parmi ceux ci-dessous pour se connecter à votre environnement Kubernetes :

• kubectl, un CLI (ligne de commande) pour interagir avec Kubernetes — guide d’installation
• Freelens, un IDE (interface graphique) pour interagir avec Kubernetes — guide d’installation
• k9s un hybride (cli + interface graphique) pour interagir avec Kubernetes guide d’installation

Pour se connecter à votre base de données :

• Votre fichier kubeconfig configuré (variable KUBECONFIG ou ~/.kube/config)
• Un client PostgreSQL : psql, DBeaver, TablePlus, pgAdmin, DataGrip, etc.

Identifier votre cluster CNPG

kubectl

Listez les clusters PostgreSQL disponibles dans votre namespace :

kubectl get clusters.postgresql.cnpg.io -n <votre-namespace>

Vous obtiendrez une sortie similaire à :

NAME              AGE   INSTANCES   READY   STATUS                     PRIMARY
my-app-database   30d   2           2       Cluster in healthy state   my-app-database-1

Freelens

1. Ouvrez Freelens et sélectionnez votre cluster dans la barre latérale.
2. Naviguez vers Custom Resources dans le menu de gauche.
3. Recherchez le groupe postgresql.cnpg.io puis cliquez sur Cluster.
4. Sélectionnez votre namespace dans le filtre en haut de la vue.

Vous verrez la liste de vos clusters CNPG avec leur statut et le nom de l’instance primaire.

Note

Le nom sous la colonne PRIMARY correspond au pod qui accepte les connexions en lecture/écriture. Les autres instances sont des réplicas en lecture seule.

Récupérer les identifiants de connexion

Les identifiants sont stockés dans un Secret Kubernetes généré automatiquement par CNPG. Le nom du secret suit la convention <nom-du-cluster>-app.

kubectl

Lisez uniquement la clé dont vous avez besoin, plutôt que le secret entier :

# le mot de passe
kubectl get secret <nom-du-cluster>-app -n <votre-namespace> \
  -o jsonpath='{.data.password}' | base64 -d && echo

# ou l'URI de connexion complète
kubectl get secret <nom-du-cluster>-app -n <votre-namespace> \
  -o jsonpath='{.data.uri}' | base64 -d && echo

Pour voir les autres champs sans afficher leur valeur :

kubectl get secret <nom-du-cluster>-app -n <votre-namespace> \
  -o go-template='{{range $k,$v := .data}}{{$k}}{{"\n"}}{{end}}'

Attention

Évitez kubectl describe secret et kubectl get secret -o yaml : le premier affiche certaines valeurs en clair, le second les expose en base64, qui n’est pas un chiffrement. Dans les deux cas le mot de passe finit dans votre historique de terminal, et dans les journaux si la commande tourne en CI.

Freelens

1. Dans le menu de gauche, naviguez vers Config → Secrets.
2. Sélectionnez votre namespace dans le filtre.
3. Cliquez sur le secret nommé <nom-du-cluster>-app.
4. Les valeurs sont masquées par défaut — cliquez sur l’icône œil à côté de chaque champ pour les révéler.

Vous y trouverez notamment :

Clé	Description
host	Nom du service interne (cluster DNS)
port	Port PostgreSQL (généralement 5432)
dbname	Nom de la base de données
username	Utilisateur applicatif
password	Mot de passe
uri	URI de connexion complète

Lancer le port-forward

kubectl

1. Ouvrez un terminal et lancez la commande suivante :

   kubectl port-forward -n <votre-namespace> svc/<nom-du-cluster>-rw 5432:5432

   Vous devriez voir :

   Forwarding from 127.0.0.1:5432 -> 5432
   Forwarding from [::1]:5432 -> 5432

   Attention

   Si le port 5432 est déjà utilisé sur votre poste (par exemple par un PostgreSQL local), choisissez un autre port local :

   kubectl port-forward -n <votre-namespace> svc/<nom-du-cluster>-rw 15432:5432

   Vous vous connecterez alors sur localhost:15432.

2. Gardez ce terminal ouvert — le port-forward reste actif tant que la commande tourne.

3. Connectez-vous depuis un autre terminal ou votre client graphique.

Freelens

1. Dans le menu de gauche, naviguez vers Network → Services.

2. Sélectionnez votre namespace dans le filtre.

3. Repérez le service <nom-du-cluster>-rw et cliquez dessus.

4. Dans le détail du service, cliquez sur le bouton Forward Port (ou faites un clic droit → Forward Port).

5. Configurez le port-forward :

   • Port local : 5432 (ou 15432 si le port est déjà utilisé)
   • Port distant : 5432

6. Cliquez sur Start — un indicateur vert confirme que le tunnel est actif.

Astuce

Freelens affiche les port-forwards actifs en bas de la fenêtre. Vous pouvez les arrêter à tout moment en cliquant sur la croix.

Se connecter à la base

psql

psql -h localhost -p 5432 -U <username> -d <dbname>

Le mot de passe vous sera demandé interactivement.

URI de connexion

Pour les clients qui acceptent une URI (DBeaver, TablePlus, etc.) :

postgresql://<username>:<password>@localhost:5432/<dbname>

Attention

Si votre mot de passe contient des caractères spéciaux (@, #, %, etc.), pensez à les encoder en URL — ou utilisez plutôt les champs séparés dans votre client.

DBeaver / pgAdmin

Remplissez les champs de connexion comme suit :

Champ	Valeur
Hôte	localhost
Port	5432 (ou le port local choisi)
Base de données	La valeur dbname du secret
Utilisateur	La valeur username du secret
Mot de passe	La valeur password du secret
SSL	Désactivé (le tunnel est local)

Connexion en lecture seule (réplica)

Pour vous connecter à un réplica en lecture seule (utile pour des requêtes lourdes sans impacter la production), il suffit de cibler le service -ro au lieu de -rw :

kubectl

kubectl port-forward -n <votre-namespace> svc/<nom-du-cluster>-ro 5432:5432

Freelens

Suivez la même procédure que pour le port-forward principal, mais sélectionnez le service <nom-du-cluster>-ro au lieu de <nom-du-cluster>-rw.

Note

Les services CNPG suivent cette convention :

• <nom>-rw → instance primaire (lecture/écriture)
• <nom>-ro → réplicas (lecture seule)
• <nom>-r → toutes les instances (round-robin)

Résolution de problèmes

Le port-forward se coupe régulièrement

C’est un comportement normal lors de périodes d’inactivité. Relancez simplement le port-forward. Freelens gère automatiquement la reconnexion dans la plupart des cas ; avec kubectl, vous pouvez utiliser un wrapper comme kubefwd pour les reconnexions automatiques.

error: unable to forward port because pod is not running

Vérifiez l’état de votre cluster CNPG :

kubectl

kubectl get pods -n <votre-namespace> -l cnpg.io/cluster=<nom-du-cluster>

Si les pods ne sont pas en état Running, consultez les événements :

kubectl describe cluster <nom-du-cluster> -n <votre-namespace>

Freelens

1. Naviguez vers Workloads → Pods.
2. Filtrez par votre namespace et recherchez les pods dont le nom commence par <nom-du-cluster>.
3. Vérifiez que leur statut est Running. Si ce n’est pas le cas, cliquez sur un pod pour consulter les Events en bas de la page de détail.

connection refused sur localhost

Assurez-vous que le port-forward est toujours actif — vérifiez votre terminal (kubectl) ou la barre de statut en bas de Freelens.