API-nøgleadgange

En API-nøgle autentificerer et program — CI, et script, Terraform — mod Frostmoln-API'et. Hver nøgle bærer adgange (scopes): listen over det, den har lov til at gøre. Frostmolns nøgler følger mindste privilegium, så en nøgle gør ingenting, før du angiver, hvad den må.

Listen leveres af platformen

Der er ingen fast liste at kopiere ud af denne side. Kataloget ligger i platformen, så det altid svarer til det, oprettelsen af en nøgle accepterer. Læs det på den flade, du arbejder på:

Hvor	Hvordan
Portalen	Indstillinger → API-nøgler → Opret API-nøgle. Adgangsvælgeren viser hver adgang med en beskrivelse af, hvad den giver.
CLI	fm account api-key scopes (tilføj -o json for at scripte det).
Terraform	Datakilden frostmoln_api_key_scopes — kør terraform console, og derefter data.frostmoln_api_key_scopes.all.scopes.

Sådan ser en adgang ud

En adgang skrives som <service>:<action>:

compute:read     læs compute-ressourcer
compute:write    opret, ændr og slet dem
storage:read     læs volumener og buckets
billing:read     læs fakturaer og forbrug

For næsten alle tjenester er read og write de to handlinger, API'et håndhæver (adgangene til interaktive sessioner er en klasse for sig — se nedenfor). write dækker enhver ændring — opret, opdater, slet samt handlinger som start/stop/genstart. Der findes ingen separat "opret, men slet ikke"-adgang: når du har brug for den skelnen, skal du bruge en adgangspolitik.

Tildel read og write, ikke de finere former

Kataloget viser også tredelte poster som compute:instances:read, og oprettelsen af en nøgle accepterer dem. De håndhæves ikke som nøgleadgange — de hører til adgangspolitik-motoren. En nøgle, der kun har compute:instances:read, oprettes uden fejl og nægtes derefter ved enhver compute-anmodning med en 403, der ikke forklarer hvorfor.

Det samme gælder de fleste af de øvrige verber, kataloget bærer (action, create, update, delete, list): de kan tildeles, men tjenesterne kontrollerer :read og :write. Tildel dem.

Adgangene til interaktive sessioner er en klasse for sig.sessions:forward, sessions:pty og sessions:write er rigtige adgangsstrenge, fordi en session er sit eget privilegium snarere end en operation på den ressource, den når. Intet andet træder i deres sted: compute:action er ikke den adgang, der åbner en shell på en instans, og kubernetes:* er ikke den, der åbner proxyen til klynge-API'et. Tildel dem til enhver nøgle, der kører fm forward, fm database <engine> console, fm shell eller fm kubernetes cluster proxy.

De kontrolleres, når nøglen oprettes: du kan ikke give en nøgle en adgang, som din egen rolle ikke har, så sessions:pty kræver rollen Owner, Administrator, Developer eller Member. De kontrolleres endnu ikke, når en session åbnes — i dag kan en nøgle, der mangler dem, stadig åbne en. Tildel dem allerede nu, så dine nøgler er rigtige, når den kontrol træder i kraft.

Jokertegn

Adgang	API-nøgle	Arbejdslastidentitet
* (alt)	Afvises — WILDCARD_SCOPE_NOT_ALLOWED	Afvises — WILDCARD_SCOPE_FORBIDDEN
compute:* (én tjeneste)	Tillades	Afvises — WILDCARD_SCOPE_FORBIDDEN
compute:read	Tillades	Tillades

En Arbejdslastidentitet-binding er bevidst strengere end en API-nøgle: en fødereret pod-legitimationsoplysning skal navngive det, den har brug for.

Bemærk, at compute:* er en reel tildeling af alt, hvad den tjeneste tilbyder, nu og i fremtiden. To navngivne adgange er næsten altid det bedre valg.

Regler værd at kende

• Mindst én adgang er påkrævet. En tom liste afvises med SCOPES_REQUIRED og en ukendt adgang med INVALID_SCOPES (ved oprettelse af en nøgle; INVALID_SCOPE ved opdatering af en nøgle eller en arbejdslastidentitets-binding).
• En nøgle kan aldrig overgå dig — i det øjeblik du opretter den. Adgangene er begrænset af tilladelserne hos den identitet, der opretter nøglen; at bede om mere fejler med SCOPE_EXCEEDS_PERMISSIONS. Dette kontrolleres, når nøglen oprettes, eller når dens adgange ændres. Hvis dine tilladelser reduceres senere, beholder allerede udstedte nøgler de adgange, de fik tildelt — tilbagekald dem, og udsted dem på ny.
• Kontrol over organisationen kræver en person, der er logget ind, ikke en nøgle. At slette en organisation, ændre et medlems rolle, fjerne et medlem, forlade en organisation og overdrage ejerskab afvises for alle API-nøgler, uanset hvad nøglen er afgrænset til — også *. En nøgle med organizations:write får USER_SESSION_REQUIRED; en nøgle uden den får insufficient_scope først. Gør det i portalen, mens du er logget ind. At forlade en organisation findes endnu ikke i portalen, så bed en administrator eller ejeren om at fjerne dig (en administrator skal bede ejeren); en ejer skal først overdrage ejerskabet og derefter bede den nye ejer. Andre ændringer på organisationsniveau, fx at invitere medlemmer, kræver organizations:write på nøglen og en organisationsrolle, der tillader dem.
• En nøgle når én organisation: den, der ejer dens tenant. Selv om du er medlem af flere organisationer, kan en nøgle oprettet i en tenant i den ene ikke læse eller ændre en anden. Lister du organisationer med nøglen, vises kun den ene, og enhver anden organisation afvises med ORGANIZATION_ACCESS_DENIED. Opret en nøgle i en tenant i hver organisation, du automatiserer.
• De fleste fm tenant-kommandoer kræver organizations:read. At liste tenants, skifte med fm tenant use og læse standardtags med fm tenant default-tags get kræver organizations:read. At oprette eller omdøbe en tenant eller ændre dens standardtags kræver organizations:write, og at oprette en uden --organization kræver desuden organizations:read. fm tenant current kræver ingen af dem. Hverken fm eller portalen kan ændre adgangene for en eksisterende nøgle (Terraform-ressourcen frostmoln_api_key kan opdatere en nøgle, den har oprettet): opret en ny nøgle, skift til den med fm auth api-key set, og tilbagekald derefter den gamle med fm account api-key revoke.
• Kvoteanmodninger kræver quotas:write. At sende eller annullere en anmodning med fm tenant quota request kræver quotas:write, og at liste anmodninger kræver quotas:read. compute:write og compute:* giver det ikke: en godkendt forhøjelse for en tenant hæver et udgiftsloft, og det er en anden adgang end at oprette ressourcer. Eksisterende nøgler har ikke fået den nye adgang, så automatisering, der sender kvoteanmodninger, skal bruge en ny nøgle med quotas:write. En workload identity kan have quotas:read, men aldrig quotas:write. At læse selve kvoterne (fm tenant quota, datakilden frostmoln_tenant_quotas) kræver ingen af dem.

Valg af adgange

Tag udgangspunkt i den opgave, nøglen udfører, ikke i den tjeneste, den taler med.

Nøglen gør dette	Tildel
Overvågning / opgørelse	compute:read, storage:read, network:read — læsningerne af det, den inspicerer
CI, der udruller instanser	compute:read, compute:write
Genstart en tjeneste planlagt	compute:read, compute:write (en handling er en ændring)
Terraform, der styrer en stak	read og write for hver tjeneste i stakken — en plan læser, før den ændrer noget
Læs fakturaer til bogføring	billing:read
Anmod om kvoteændringer	quotas:read, quotas:write

To vaner holder nøgler sikre: giv en nøgle ét job i stedet for at genbruge en bred nøgle, og sæt en udløbsdato, så en glemt nøgle holder op med at virke af sig selv.

Eksempler

CLI

# Se, hvad du kan tildele, og opret derefter nøglen
fm account api-key scopes
fm account api-key create --name "ci-deploy" \
  --scopes compute:read,compute:write \
  --expires 2027-01-01

Terraform

data "frostmoln_api_key_scopes" "all" {}

resource "frostmoln_api_key" "ci" {
  name   = "ci-deploy"
  scopes = ["compute:read", "compute:write"]
}

Selve nøglen vises én gang, når den oprettes. Læg den i din hemmelighedshåndtering med det samme — den kan ikke hentes bagefter, kun erstattes.

Når adgange ikke er nok

Adgange fortæller, hvilken slags kald en nøgle må foretage, aldrig på hvilken ressource eller hvorfra. Når du har brug for "må oprette instanser, men aldrig slette dem", "kun i én region", "kun fra kontornetværket" eller en eksplicit nægtelse, skal du bruge en adgangspolitik. Det er der, de finkornede service:resource:action-operationer gælder, og en politik tilknyttes de samme API-nøgler.