Distributions of transverse momentum $p_T^{ll}$ and the angular variable $\phi^*_\eta$ of Drell--Yan lepton pairs are measured in 20.3 fb$^{-1}$ of proton--proton collisions at $\sqrt{s}=8$ TeV with the ATLAS detector at the LHC. Measurements in electron-pair and muon-pair final states are corrected for detector effects and combined. Compared to previous measurements in proton--proton collisions at $\sqrt{s}=7$ TeV, these new measurements benefit from a larger data sample and improved control of systematic uncertainties. Measurements are performed in bins of lepton-pair mass above, around and below the Z-boson mass peak. The data are compared to predictions from perturbative and resummed QCD calculations. For values of $\phi^*_\eta < 1$ the predictions from the Monte Carlo generator ResBos are generally consistent with the data within the theoretical uncertainties. However, at larger values of $\phi^*_\eta$ this is not generally the case. Monte Carlo generators based on the parton-shower approach are unable to describe the data over the full range of $p_T^{ll}$ and the fixed-order prediction of DYNNLO falls below the data at high values of $p_T^{ll}$. ResBos and the parton-shower Monte Carlo generators provide a much better description of the evolution of the $\phi^*_\eta$ and $p_T^{ll}$ distributions as a function of lepton-pair mass and rapidity.